ENH: improve FreeSurfer error message when executable not found#13790
ENH: improve FreeSurfer error message when executable not found#13790ayuclan wants to merge 4 commits intomne-tools:mainfrom
Conversation
Closes mne-tools#12917 Improved error message when FreeSurfer executable (e.g., mri_watershed) cannot be found. - Clarifies need for proper FreeSurfer setup - Mentions adding $FREESURFER_HOME/bin to PATH - Notes that Python/Jupyter should be started from configured shell This helps users diagnose common setup issues more easily.
for more information, see https://pre-commit.ci
|
Hi, this is my first contribution to MNE. I’ve added a clearer error message for missing FreeSurfer executables. I also saw pre-commit auto-fixes applied—please let me know if any further changes or formatting adjustments are needed. Thanks! |
|
If we don't opt for some magic solution where MNE-Python tries to go the FreeSurfer setup itself, then this is indeed a much better error message. Thanks @ayuclan! |
mne/bem.py
Outdated
| "Make sure:\n" | ||
| "- FREESURFER_HOME is set\n" | ||
| "- $FREESURFER_HOME/bin is in your PATH\n" | ||
| "- You started Python/Jupyter from a terminal where FreeSurfer is sourced\n\n" |
There was a problem hiding this comment.
Perhaps this is even clearer?
| "- You started Python/Jupyter from a terminal where FreeSurfer is sourced\n\n" | |
| "- You started Python/Jupyter from a terminal where SetupFreeSurfer.sh is sourced\n\n" |
There was a problem hiding this comment.
Or is it FreeSurferEnv.sh these days?
There was a problem hiding this comment.
Thanks for the suggestion! I’ll update the message to make it more specific.
From what I understand, SetupFreeSurfer.sh is commonly used, but I’ll verify whether FreeSurferEnv.sh is also relevant and adjust accordingly. Please let me know if you have a preferred wording.
There was a problem hiding this comment.
Or is it
FreeSurferEnv.shthese days?
Applied the suggestion, thank you!
There was a problem hiding this comment.
I'm on freesurfer 8.2.0 and for me SetupFreeSurfer.sh does not exist, but instead it is FreeSurferEnv.sh. Did they change the name across versions?
ENH: refine FreeSurfer setup error message Co-authored-by: Marijn van Vliet <w.m.vanvliet@gmail.com>
JiwaniZakir
left a comment
There was a problem hiding this comment.
The error handling in bem.py catches FileNotFoundError specifically for the mri_watershed executable, but the error message hardcodes that name rather than referencing the actual command from cmd[0]. If run_subprocess_env raises FileNotFoundError for a different reason — e.g., an input file path issue on some platforms — the message will be misleading. Consider either extracting the executable name dynamically (cmd[0]) or at minimum catching the exception as e and checking e.filename to verify it matches the expected executable before reraising with the custom message. Additionally, it's worth adding a test case that mocks run_subprocess_env to raise FileNotFoundError and asserts that the resulting RuntimeError message contains the expected guidance text, since this new branch is currently untested. The documentation link at the end of the message ("See MNE installation documentation for details.") would be more useful if it included an actual URL.
Thanks for the detailed feedback. I’ll work on these changes and update the PR soon. |
Closes #12917
Improved error message when FreeSurfer executable (e.g., mri_watershed) cannot be found.
This helps users diagnose common setup issues more easily.