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

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 3 people

doc/changes/dev/13874.bugfix.rst

@@ -0,0 +1 @@
+Improved error message when FreeSurfer executable is not found, by :newcontrib:`Ayushi Satodiya`.

doc/changes/names.inc

@@ -35,6 +35,7 @@
 .. _Ashley Drew: https://github.com/ashdrew
 .. _Asish Panda: https://github.com/kaichogami
 .. _Austin Hurst: https://github.com/a-hurst
+.. _Ayushi Satodiya: https://github.com/ayuclan
 .. _Beige Jin: https://github.com/BeiGeJin
 .. _Ben Beasley: https://github.com/musicinmybrain
 .. _Benedikt Ehinger: https://www.benediktehinger.de

mne/bem.py

@@ -1313,7 +1313,19 @@ def make_watershed_bem(
         f"\nResults dir = {ws_dir}\nCommand = {' '.join(cmd)}\n"
     )
     os.makedirs(op.join(ws_dir))
-    run_subprocess_env(cmd)
+    try:
+        run_subprocess_env(cmd)
+    except FileNotFoundError as e:
+        raise RuntimeError(
+            "FreeSurfer executable 'mri_watershed' not found.\n\n"
+            "This usually means FreeSurfer is not properly configured.\n"
+            "Make sure:\n"
+            "- FREESURFER_HOME is set\n"
+            "- $FREESURFER_HOME/bin is in your PATH\n"
+            "- You started Python/Jupyter from a terminal where "
+            "SetupFreeSurfer.sh is sourced\n\n"
+            "See https://mne.tools/stable/install/index.html for details."
+        ) from e
     del tempdir  # clean up directory
     if op.isfile(T1_mgz):
         new_info = _extract_volume_info(T1_mgz)