oraios/serena · error · RuntimeError

opam not found. Please install opam: https://opam.ocaml.or

Error message

opam not found. Please install opam:
  https://opam.ocaml.org/doc/Install.html

What it means

This RuntimeError is raised when the opam executable itself is not found (FileNotFoundError) while trying to detect the ocaml-lsp-server version in _detect_lsp_version. It mirrors error 282 but originates from the version-detection path rather than the initial opam presence check, and simply directs the user to the opam installation docs.

Source

Thrown at src/solidlsp/language_servers/ocaml_lsp_server.py:141

            version_match = re.search(r"(\d+)\.(\d+)\.(\d+)", version_str)
            if version_match:
                major = int(version_match.group(1))
                minor = int(version_match.group(2))
                patch = int(version_match.group(3))
                version_tuple = (major, minor, patch)
                log.info(f"ocaml-lsp-server version: {major}.{minor}.{patch}")
                return version_tuple
            raise RuntimeError(
                f"Could not parse ocaml-lsp-server version from output: {version_str}\n"
                "Please ensure ocaml-lsp-server is properly installed:\n"
                "  opam list -i ocaml-lsp-server"
            )
        except subprocess.CalledProcessError as e:
            raise RuntimeError(
                f"Failed to detect ocaml-lsp-server version: {e.stderr}\nPlease install ocaml-lsp-server:\n  opam install ocaml-lsp-server"
            ) from e
        except FileNotFoundError as e:
            raise RuntimeError("opam not found. Please install opam:\n  https://opam.ocaml.org/doc/Install.html") from e

    @staticmethod
    def _ensure_ocaml_lsp_installed(repository_root_path: str) -> str:
        """
        Ensure ocaml-lsp-server is installed and return the executable path.
        Raises RuntimeError with helpful message if not installed.
        """
        # Check if ocaml-lsp-server is installed
        try:
            result = subprocess_run(
                ["opam", "list", "-i", "ocaml-lsp-server"],
                check=False,
                capture_output=True,
                text=True,
                cwd=repository_root_path,
                **subprocess_kwargs(),
            )
            if "ocaml-lsp-server" not in result.stdout or "# No matches found" in result.stdout:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install opam following https://opam.ocaml.org/doc/Install.html for your platform.
Ensure the opam bin directory is on PATH for the exact process running the code (export PATH="$HOME/.opam/default/bin:$PATH" or eval $(opam env)).
Verify with 'which opam' in the same environment (IDE-spawned shells may differ).
Initialize after install: opam init, then create/activate a switch before starting the server.

Example fix

// before: launching from IDE with minimal env
spawn(process, { env: { PATH: "/usr/bin:/bin" } })
// after
spawn(process, { env: { PATH: process.env.PATH + ":" + os.homedir() + "/.opam/default/bin" } })

Defensive patterns

Strategy: validation

Validate before calling

import shutil, os

def require_opam_on_path() -> str:
    opam = shutil.which("opam")
    if opam is None:
        candidates = os.path.expanduser("~/.opam/default/bin")
        raise RuntimeError(
            f"opam not found on PATH (checked {os.environ.get('PATH','')!r}). "
            f"Install opam and ensure {candidates} is exported in the launching environment."
        )
    return opam

Try / catch

try:
    server = OcamlLanguageServer(**kwargs)
except RuntimeError as e:
    if "opam not found" in str(e):
        raise EnvironmentError(
            "opam binary unavailable to this process. Install it and add its bin dir "
            "to the PATH of the exact process starting the server."
        ) from e
    raise

Prevention

Check 'which opam' from within the same launcher (IDE/CI runner) that will start the server, not only your terminal.
Export PATH additions in the process environment, not just shell dotfiles skipped by non-login shells.
After installing opam, run 'opam init' and 'eval $(opam env)' before first use.
Add a preflight binary check (shutil.which) to your app's startup diagnostics.

When it happens

Trigger: Constructing the OCaml language server on a machine where 'opam' is not on PATH of the running process, and the failure surfaces from _detect_lsp_version's subprocess call rather than _ensure_opam_installed (e.g. PATH changed or opam removed between checks, or the check path not exercised).

Common situations: IDE/extension hosts launching the library with a sanitized PATH lacking opam's install directory; opam uninstalled mid-session; containers where opam is only available in a user's login shell profile that isn't sourced.

Related errors

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