oraios/serena · error · RuntimeError

MATLAB installation not found. Set the MATLAB_PATH environme

Error message

MATLAB installation not found. Set the MATLAB_PATH environment variable to your MATLAB installation directory (e.g., /Applications/MATLAB_R2024b.app on macOS, C:\Program Files\MATLAB\R2024b on Windows, or /usr/local/MATLAB/R2024b on Linux).

What it means

The MATLAB integration needs a local MATLAB installation to run the language server. It searches common install locations via glob patterns; if none is found, it raises RuntimeError telling you to set the MATLAB_PATH environment variable explicitly.

Source

Thrown at src/solidlsp/language_servers/matlab_language_server.py:303

                        if os.path.isdir(match):
                            log.info(f"Found MATLAB installation: {match}")
                            return match

            elif system == "Linux":
                # Check common Linux locations
                search_patterns = [
                    "/usr/local/MATLAB/R*",
                    "/opt/MATLAB/R*",
                    os.path.expanduser("~/MATLAB/R*"),
                ]
                for pattern in search_patterns:
                    matches = sorted(glob.glob(pattern), reverse=True)
                    for match in matches:
                        if os.path.isdir(match):
                            log.info(f"Found MATLAB installation: {match}")
                            return match

            raise RuntimeError(
                f"MATLAB installation not found. Set the {MATLAB_PATH_ENV_VAR} environment variable "
                "to your MATLAB installation directory (e.g., /Applications/MATLAB_R2024b.app on macOS, "
                "C:\\Program Files\\MATLAB\\R2024b on Windows, or /usr/local/MATLAB/R2024b on Linux)."
            )

        def get_matlab_path(self) -> str:
            """Get MATLAB path from settings or auto-detect."""
            if self._matlab_path is not None:
                return self._matlab_path

            matlab_path = self._custom_settings.get("matlab_path")

            if not matlab_path:
                matlab_path = self._find_matlab_installation()  # Raises RuntimeError if not found

            # Verify MATLAB path exists
            if not os.path.isdir(matlab_path):
                raise RuntimeError(f"MATLAB installation directory does not exist: {matlab_path}")

View on GitHub (pinned to 7fcbca7e62)

Solutions

Set the MATLAB_PATH environment variable to your MATLAB installation directory (e.g. /Applications/MATLAB_R2024b.app, C:\Program Files\MATLAB\R2024b, /usr/local/MATLAB/R2024b)
Verify the directory you point to actually contains the MATLAB binaries (os.path.isdir must pass)
Install MATLAB if it is not present on the machine

Example fix

# before
# (no MATLAB_PATH set)
# after
export MATLAB_PATH=/usr/local/MATLAB/R2024b

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("MATLAB_PATH"):
    for p in ("/usr/local/MATLAB/R2024b", "/Applications/MATLAB_R2024b.app",
              "C:\\Program Files\\MATLAB\\R2024b"):
        if os.path.isdir(p):
            os.environ["MATLAB_PATH"] = p; break
    else:
        raise RuntimeError("Set MATLAB_PATH before starting the MATLAB language server")

Type guard

def matlab_available(env_var: str = "MATLAB_PATH") -> bool:
    v = os.environ.get(env_var)
    return bool(v) and os.path.isdir(v)

Try / catch

try:
    ls = SolidLSP("matlab")
except RuntimeError as e:
    if "MATLAB installation not found" in str(e):
        os.environ["MATLAB_PATH"] = discover_matlab_dir()
        ls = SolidLSP("matlab")
    else:
        raise

Prevention

Always set MATLAB_PATH explicitly in CI/containers
Re-check the env var after MATLAB version upgrades
Verify the directory exists with os.path.isdir before launching

When it happens

Trigger: create_launch_command -> get_matlab_path with no explicit matlab_path, and _find_matlab_installation finds no directory matching its known patterns (non-standard install location, custom install prefix, or MATLAB not installed at all).

Common situations: MATLAB installed outside default paths (e.g. ~/matlab, /opt); multiple MATLAB versions in an unrecognized layout; headless CI containers with no MATLAB installed; typo'd MATLAB_PATH value.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/c44fb0a0f7ce509d. Report an issue: GitHub.