oraios/serena · error · RuntimeError

ocaml-lsp-server is not installed. Please install it with:

Error message

ocaml-lsp-server is not installed.

Please install it with:
  opam install ocaml-lsp-server

Note: ocaml-lsp-server requires OCaml < 5.1 or >= 5.1.1 (OCaml 5.1.0 is not supported).
If you have OCaml 5.1.0, create a new opam switch with a compatible version:
  opam switch create <name> ocaml-base-compiler.4.14.2
  opam switch <name>
  eval $(opam env)
  opam install ocaml-lsp-server

For more information: https://github.com/ocaml/ocaml-lsp

What it means

Raised by SolidLSP's OcamlLSPServer._ensure_ocaml_lsp_server (called from __init__) when an `opam list` query run in the repository root shows that the ocaml-lsp-server package is not installed in the current opam switch. The library requires the ocaml-lsp-server binary to start the language server and cannot proceed without it. The message also warns that OCaml 5.1.0 is unsupported by ocaml-lsp-server.

Source

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

    @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:
                raise RuntimeError(
                    "ocaml-lsp-server is not installed.\n\n"
                    "Please install it with:\n"
                    "  opam install ocaml-lsp-server\n\n"
                    "Note: ocaml-lsp-server requires OCaml < 5.1 or >= 5.1.1 (OCaml 5.1.0 is not supported).\n"
                    "If you have OCaml 5.1.0, create a new opam switch with a compatible version:\n"
                    "  opam switch create <name> ocaml-base-compiler.4.14.2\n"
                    "  opam switch <name>\n"
                    "  eval $(opam env)\n"
                    "  opam install ocaml-lsp-server\n\n"
                    "For more information: https://github.com/ocaml/ocaml-lsp"
                )
            log.info("ocaml-lsp-server is installed")
        except subprocess.CalledProcessError as e:
            raise RuntimeError(f"Failed to check ocaml-lsp-server installation: {e.stderr}")

        # Find the executable path
        try:
            if platform.system() == "Windows":

View on GitHub (pinned to 7fcbca7e62)

Solutions

Run `opam install ocaml-lsp-server` in the repository root switch.
Check the current switch with `opam switch show`; switch to one with the package: `opam switch <name>` then `eval $(opam env)`.
If on OCaml 5.1.0, create a compatible switch: `opam switch create <name> ocaml-base-compiler.4.14.2` then `eval $(opam env)` and install the package.
Verify with `opam list | grep ocaml-lsp-server` that the package is visible before launching.

Example fix

// before (failing shell)
opam switch 5.1.0
eval $(opam env)  # ocaml-lsp-server not installable on 5.1.0
// after
opam switch create ocaml-414 ocaml-base-compiler.4.14.2
opam switch ocaml-414
eval $(opam env)
opam install ocaml-lsp-server

Defensive patterns

Strategy: validation

Validate before calling

import subprocess
def ensure_ocaml_lsp_installed(repo_root):
    r = subprocess.run(["opam", "list", "--", "ocaml-lsp-server"], capture_output=True, text=True, cwd=repo_root)
    if r.returncode != 0 or "ocaml-lsp-server" not in r.stdout or "# No matches found" in r.stdout:
        raise RuntimeError("ocaml-lsp-server not installed; run: opam install ocaml-lsp-server")

Prevention

Bake `opam install ocaml-lsp-server` into your Dockerfile/CI setup step
Avoid OCaml 5.1.0 switches (unsupported); pin 4.14.x or >= 5.1.1
Always `eval $(opam env)` before launching the server so the right switch is visible
Verify installation in a preflight check before instantiating the server

When it happens

Trigger: Instantiating OcamlLSPServer when the active opam switch lacks ocaml-lsp-server, or when `opam list` output contains '# No matches found'. Also triggered if opam list succeeds but the package name is absent (e.g. wrong switch selected).

Common situations: Fresh OCaml environment or container without the LSP package; developer switched to a new opam switch that doesn't have ocaml-lsp-server; OCaml 5.1.0 switch where the package can't be installed; CI image missing opam packages.

Related errors

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