Skip to content

BUG: improve FreeSurfer error message when executable not found#13874

Open
ayuclan wants to merge 6 commits intomne-tools:mainfrom
ayuclan:fix-freesurfer-error-v2
Open

BUG: improve FreeSurfer error message when executable not found#13874
ayuclan wants to merge 6 commits intomne-tools:mainfrom
ayuclan:fix-freesurfer-error-v2

Conversation

@ayuclan
Copy link
Copy Markdown

@ayuclan ayuclan commented Apr 28, 2026

Fixes #12917
Improves the error message in make_watershed_bem() when the FreeSurfer
executable (mri_watershed) cannot be found.

Instead of a generic FileNotFoundError, users now get a clear RuntimeError
explaining:

  • FREESURFER_HOME needs to be set
  • $FREESURFER_HOME/bin needs to be in PATH
  • Python/Jupyter must be started from a terminal where SetupFreeSurfer.sh is sourced

The original FileNotFoundError is chained using from e for full traceback.

This is a re-submission of #13790, which had unresolvable CI issues
unrelated to the code changes. The fix itself was reviewed and approved
by @wmvanvliet .

When mri_watershed is not found, raise a RuntimeError with clear
guidance to check FREESURFER_HOME, PATH, and shell configuration.

Closes mne-tools#12917
Re-submission of mne-tools#13790
@welcome
Copy link
Copy Markdown

welcome Bot commented Apr 28, 2026

Hello! 👋 Thanks for opening your first pull request here! ❤️ We will try to get back to you soon. 🚴

Comment thread doc/changes/names.inc
.. _Jukka Nenonen: https://www.linkedin.com/pub/jukka-nenonen/28/b5a/684
.. _Jussi Nurminen: https://github.com/jjnurminen
.. _Kaisu Lankinen: http://bishoplab.berkeley.edu/Kaisu.html
.. _Kalle Makela: https://github.com/Kallemakela
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why remove these?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry about that! The accidental deletions were caused by Ctrl+Z in my editor. I've restored all the missing entries now.

@ayuclan ayuclan force-pushed the fix-freesurfer-error-v2 branch from a16bfb7 to e283134 Compare April 28, 2026 11:39
@ayuclan ayuclan force-pushed the fix-freesurfer-error-v2 branch from 7e59ac1 to 0d4f084 Compare April 28, 2026 11:53
@wmvanvliet
Copy link
Copy Markdown
Contributor

Looks like opening a new PR fixed the doc build!

Copy link
Copy Markdown
Member

@larsoner larsoner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wmvanvliet I just pushed a commit to fix the changelog, feel free to mark for merge-when-green when you're happy

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Provide more helpful error message if FreeSurfer executables cannot be found; consider amending install docs

3 participants