oraios/serena · error · RuntimeError

Failed to detect ocaml-lsp-server version: {e.stderr} Please

Error message

Failed to detect ocaml-lsp-server version: {e.stderr}
Please install ocaml-lsp-server:
  opam install ocaml-lsp-server

What it means

This RuntimeError is raised when the command used to detect the ocaml-lsp-server version exits with a non-zero status (subprocess.CalledProcessError), almost always because the ocaml-lsp-server opam package is not installed. The stderr is surfaced along with the fix command 'opam install ocaml-lsp-server'.

Source

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

                cwd=repository_root_path,
                **subprocess_kwargs(),
            )
            version_str = result.stdout.strip()
            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,

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install the language server: opam install ocaml-lsp-server, then eval $(opam env).
If on a fresh switch, also ensure the base compiler and toolchain are installed (opam init / opam switch create ...).
Check stderr in the message for the real opam error and address it (network, repo not updated: opam update).
Verify installation: opam list -i ocaml-lsp-server.

Example fix

// before (shell)
opam switch create proj 5.1.1   # ocaml-lsp-server not installed
// after
opam switch create proj 5.1.1
opam install -y ocaml-lsp-server
eval $(opam env)

Defensive patterns

Strategy: validation

Validate before calling

import subprocess

def require_ocaml_lsp_installed() -> None:
    r = subprocess.run(
        ["opam", "list", "--installed", "ocaml-lsp-server"],
        capture_output=True, text=True,
    )
    if r.returncode != 0 or not r.stdout.strip():
        raise RuntimeError(
            "ocaml-lsp-server not installed in the active switch. "
            "Run: opam install ocaml-lsp-server && eval $(opam env)"
        )

Try / catch

try:
    server = OcamlLanguageServer(**kwargs)
except RuntimeError as e:
    if "Failed to detect ocaml-lsp-server version" in str(e):
        logger.error("Install the language server: opam install ocaml-lsp-server, then eval $(opam env). stderr: %s", e)
        raise
    raise

Prevention

Add 'opam install -y ocaml-lsp-server' to setup scripts for every new switch, not just the first.
Run 'opam list -i ocaml-lsp-server' as a CI preflight before starting OCaml language services.
When caching opam roots in CI, include the language-server package in the cache key.
After creating any new opam switch, reinstall project dependencies including ocaml-lsp-server.

When it happens

Trigger: Constructing the OCaml language server when the version-detection subprocess fails: ocaml-lsp-server missing from the active switch, opam query erroring, or a broken switch causing non-zero exit.

Common situations: New opam switch where only the compiler was installed and language-server packages were not; CI caching that skipped opam install steps; switch created after forgetting to install ocaml-lsp-server.

Related errors

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