What causes "OCaml 5.1.0 is incompatible with ocaml-lsp-server. Please use OCaml = 5.1.1. Consider creating a new opam switch: opam switch create ocaml-base-compiler.4.14.2" in oraios/serena?

Create a new opam switch with a compatible compiler: opam switch create ocaml-base-compiler.4.14.2 (or >= 5.1.1).

oraios/serena · error · RuntimeError

OCaml 5.1.0 is incompatible with ocaml-lsp-server. Please us

Error message

OCaml 5.1.0 is incompatible with ocaml-lsp-server.
Please use OCaml < 5.1 or >= 5.1.1.
Consider creating a new opam switch:
  opam switch create <name> ocaml-base-compiler.4.14.2

What it means

This RuntimeError is raised because ocaml-lsp-server is known to be incompatible with exactly OCaml 5.1.0. _detect_ocaml_version runs 'opam exec -- ocaml -version', parses the triple, and deliberately rejects the (5,1,0) tuple at startup. The error advises using OCaml < 5.1 or >= 5.1.1 via a new opam switch.

Source

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

            result = subprocess_run(
                ["opam", "exec", "--", "ocaml", "-version"],
                check=True,
                capture_output=True,
                text=True,
                cwd=repository_root_path,
                **subprocess_kwargs(),
            )
            version_match = re.search(r"(\d+)\.(\d+)\.(\d+)", result.stdout)
            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)
                version_str = f"{major}.{minor}.{patch}"
                log.info(f"OCaml version: {version_str}")

                if version_tuple == (5, 1, 0):
                    raise RuntimeError(
                        f"OCaml {version_str} is incompatible with ocaml-lsp-server.\n"
                        "Please use OCaml < 5.1 or >= 5.1.1.\n"
                        "Consider creating a new opam switch:\n"
                        "  opam switch create <name> ocaml-base-compiler.4.14.2"
                    )
                return version_tuple
            raise RuntimeError(
                f"Could not parse OCaml version from output: {result.stdout.strip()}\n"
                "Please ensure OCaml is properly installed: opam exec -- ocaml -version"
            )
        except subprocess.CalledProcessError as e:
            raise RuntimeError(
                f"Failed to detect OCaml version: {e.stderr}\n"
                "Please ensure OCaml is installed and opam is configured:\n"
                "  opam switch show\n"
                "  opam exec -- ocaml -version"
            ) from e
        except FileNotFoundError as e:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Create a new opam switch with a compatible compiler: opam switch create <name> ocaml-base-compiler.4.14.2 (or >= 5.1.1).
Run eval $(opam env) to activate the new switch, then retry.
Alternatively upgrade the existing switch: opam switch set <switch-with-5.1.1+> or reinstall packages on 5.1.1.
Verify with 'opam exec -- ocaml -version' that the active compiler is not 5.1.0.

Example fix

// before (shell)
opam switch list  # shows 5.1.0 active
// after
opam switch create ocaml-5-1-1 ocaml-base-compiler.5.1.1
eval $(opam env)

Defensive patterns

Strategy: validation

Validate before calling

import re, subprocess

def require_compatible_ocaml() -> tuple:
    out = subprocess.run(
        ["opam", "exec", "--", "ocaml", "-version"],
        capture_output=True, text=True, check=True,
    ).stdout
    m = re.search(r"(\d+)\.(\d+)\.(\d+)", out)
    if not m:
        raise RuntimeError(f"Cannot parse OCaml version from: {out!r}")
    v = tuple(map(int, m.groups()))
    if v == (5, 1, 0):
        raise RuntimeError(
            "OCaml 5.1.0 is incompatible with ocaml-lsp-server; "
            "use < 5.1 or >= 5.1.1 (e.g. opam switch create <name> ocaml-base-compiler.5.1.1)"
        )
    return v

Try / catch

try:
    server = OcamlLanguageServer(**kwargs)
except RuntimeError as e:
    if "5.1.0" in str(e) and "incompatible" in str(e):
        raise SystemExit(
            "Pin the project switch to a compatible compiler: "
            "opam switch create proj ocaml-base-compiler.5.1.1 && eval $(opam env)"
        ) from e
    raise

Prevention

Pin the switch compiler in your project (e.g. *.opam.locked / CI setup-opam step) and avoid 5.1.0.
Check 'opam exec -- ocaml -version' as a preflight in CI before starting the server.
Keep switch definitions in version control so all devs get a compatible compiler.
If forced onto 5.1.0 by a dependency, upgrade to >= 5.1.1 which contains the fix.

When it happens

Trigger: Constructing the OCaml language server while the active opam switch uses OCaml 5.1.0; _detect_ocaml_version parses version 5.1.0 from 'ocaml -version' output and hits the explicit version_tuple == (5, 1, 0) check.

Common situations: A project pinned to OCaml 5.1.0 in its opam switch; a newly created switch defaulting to 5.1.0 before the 5.1.1 patch; team lockfiles that selected the buggy release.

Related errors

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