ENH: improve FreeSurfer error message when executable not found

[ayuclan]

Closes #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.

[ayuclan]

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!

[wmvanvliet]

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!

[wmvanvliet]

Perhaps this is even clearer?

Suggested change

	"- 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"

[wmvanvliet]

Or is it FreeSurferEnv.sh these days?

[ayuclan]

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.

[ayuclan]

Or is it FreeSurferEnv.sh these days?

Applied the suggestion, thank you!

[wmvanvliet]

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?

[JiwaniZakir]

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.

[ayuclan]

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.