oraios/serena · error · RuntimeError

OPAM is not installed or not in PATH. Please install OPAM fr

Error message

OPAM is not installed or not in PATH.
Please install OPAM from: https://opam.ocaml.org/doc/Install.html

Installation instructions:
  - macOS: brew install opam
  - Ubuntu/Debian: sudo apt install opam
  - Fedora: sudo dnf install opam
  - Windows: https://fdopen.github.io/opam-repository-mingw/installation/

After installation, initialize OPAM with: opam init

What it means

This RuntimeError is raised when the 'opam' executable cannot be found on PATH, which is a hard prerequisite for the ocaml-lsp-server integration. _ensure_opam_installed calls shutil.which('opam') during server __init__ and fails fast with platform-specific install instructions. Language server startup is aborted.

Source

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

class OcamlLanguageServer(SolidLanguageServer):
    """
    Provides OCaml and Reason specific instantiation of the SolidLanguageServer class.
    Contains various configurations and settings specific to OCaml and Reason.
    """

    _ocaml_version: tuple[int, int, int]
    _lsp_version: tuple[int, int, int]
    _index_built: bool

    # Minimum LSP version for reliable cross-file references
    MIN_LSP_VERSION_FOR_CROSS_FILE_REFS: tuple[int, int, int] = (1, 23, 0)

    @staticmethod
    def _ensure_opam_installed() -> None:
        """Ensure OPAM is installed and available."""
        opam_path = shutil.which("opam")
        if opam_path is None:
            raise RuntimeError(
                "OPAM is not installed or not in PATH.\n"
                "Please install OPAM from: https://opam.ocaml.org/doc/Install.html\n\n"
                "Installation instructions:\n"
                "  - macOS: brew install opam\n"
                "  - Ubuntu/Debian: sudo apt install opam\n"
                "  - Fedora: sudo dnf install opam\n"
                "  - Windows: https://fdopen.github.io/opam-repository-mingw/installation/\n\n"
                "After installation, initialize OPAM with: opam init"
            )

    @staticmethod
    def _detect_ocaml_version(repository_root_path: str) -> tuple[int, int, int]:
        """
        Detect and return the OCaml version as a tuple (major, minor, patch).
        Also checks for version compatibility with ocaml-lsp-server.
        Raises RuntimeError if version cannot be determined.
        """
        try:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install opam per platform: brew install opam (macOS), sudo apt install opam (Ubuntu/Debian), sudo dnf install opam (Fedora), or the Windows mingw installer.
Run 'opam init' after installing to initialize the opam root.
Ensure the opam binary directory is on PATH for the process that launches the language server (eval $(opam env) or export PATH).
Verify with 'which opam' in the same shell/environment that runs the code.

Example fix

// before: subprocess env lacks opam
// after (shell)
eval $(opam env)   # or: export PATH="$HOME/.opam/default/bin:$PATH"
python -c "import mylib; mylib.OcamlLsp(...)"

Defensive patterns

Strategy: validation

Validate before calling

import shutil

def require_opam() -> str:
    opam = shutil.which("opam")
    if opam is None:
        raise RuntimeError(
            "opam not on PATH. Install: https://opam.ocaml.org/doc/Install.html "
            "and run 'opam init'"
        )
    return opam

Try / catch

try:
    server = OcamlLanguageServer(**kwargs)
except RuntimeError as e:
    if "OPAM is not installed" in str(e):
        raise EnvironmentError(
            "OCaml toolchain prerequisite missing. Run the documented opam install "
            "for your platform, then 'opam init'."
        ) from e
    raise

Prevention

Run 'which opam' in the exact environment (CI job, IDE-spawned shell) that will start the server.
Include opam in Dockerfiles/CI images and run 'opam init' during build.
Remember non-login shells skip ~/.profile; set PATH in the launcher, not just dotfiles.
Document the opam prerequisite next to the library usage in your repo.

When it happens

Trigger: Constructing the OCaml language server on a machine where opam is not installed, or installed but not on the PATH of the process running the library (e.g. missing from CI image, IDE-spawned process env, or non-interactive shell).

Common situations: Fresh Docker/CI container without opam; opam installed under ~/.opam or via a user-local toolchain not added to PATH in non-login shells; Windows without the opam mingw installer; macOS without brew install opam.

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/6a4a42254e5364d7. Report an issue: GitHub.