What causes "OCaml not found. Please install OCaml via opam: opam switch create ocaml-base-compiler.4.14.2 eval $(opam env)" in oraios/serena?

Create/repair a compiler switch: opam switch create ocaml-base-compiler.4.14.2 then eval $(opam env).

oraios/serena · error · RuntimeError

OCaml not found. Please install OCaml via opam: opam switc

Error message

OCaml not found. Please install OCaml via opam:
  opam switch create <name> ocaml-base-compiler.4.14.2
  eval $(opam env)

What it means

This RuntimeError is raised when the OCaml compiler binary itself cannot be found: 'opam exec -- ocaml -version' raised FileNotFoundError. Unlike error 282 (opam missing), here opam exists but cannot locate or execute the ocaml binary. The message suggests creating a compiler via opam switch.

Source

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

                        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:
            raise RuntimeError(
                "OCaml not found. Please install OCaml via opam:\n"
                "  opam switch create <name> ocaml-base-compiler.4.14.2\n"
                "  eval $(opam env)"
            ) from e

    @staticmethod
    def _detect_lsp_version(repository_root_path: str) -> tuple[int, int, int]:
        """
        Detect and return the ocaml-lsp-server version as a tuple (major, minor, patch).
        Raises RuntimeError if version cannot be determined.
        """
        try:
            result = subprocess_run(
                ["opam", "list", "-i", "ocaml-lsp-server", "--columns=version", "--short"],
                check=True,
                capture_output=True,
                text=True,
                cwd=repository_root_path,

View on GitHub (pinned to 7fcbca7e62)

Solutions

Create/repair a compiler switch: opam switch create <name> ocaml-base-compiler.4.14.2 then eval $(opam env).
Check 'opam switch list' and select an existing valid switch: opam switch set <name>.
If the switch directory is corrupted, remove it (opam switch remove <name>) and recreate it.
Confirm with 'opam exec -- ocaml -version' that ocaml now runs.

Example fix

// before (shell)
opam switch list  # empty or broken
// after
opam switch create myproj ocaml-base-compiler.4.14.2
eval $(opam env)
opam install -y ocaml-lsp-server

Defensive patterns

Strategy: validation

Validate before calling

import shutil, subprocess

def require_ocaml_compiler() -> None:
    if shutil.which("opam") is None:
        raise RuntimeError("opam missing; install from https://opam.ocaml.org/doc/Install.html")
    r = subprocess.run(
        ["opam", "exec", "--", "ocaml", "-version"], capture_output=True, text=True,
    )
    if r.returncode != 0 or "version" not in r.stdout:
        raise RuntimeError(
            "ocaml compiler not available via opam. Create a switch: "
            "opam switch create <name> ocaml-base-compiler.4.14.2 && eval $(opam env)"
        )

Try / catch

try:
    server = OcamlLanguageServer(**kwargs)
except RuntimeError as e:
    if "OCaml not found" in str(e):
        logger.error("Create/repair an opam switch with a compiler, then eval $(opam env): %s", e)
        raise
    raise

Prevention

Verify 'opam switch list' shows a switch with an installed compiler before starting dev work.
After recreating or switching environments, always 'eval $(opam env)' before launching servers.
Avoid deleting switch directories manually; use 'opam switch remove'.
In CI, cache the full opam root including the compiler, not just opam itself.

When it happens

Trigger: Constructing the OCaml language server when opam is on PATH but no switch contains the ocaml compiler, or the switch's bin directory is missing/corrupted, causing FileNotFoundError from the subprocess call in _detect_ocaml_version.

Common situations: Fresh opam install with no switches created; switch deleted or its ~/.opam/<switch> directory removed while still selected; partially failed switch install leaving ocaml absent; PATH stripped so opam's env can't resolve ocaml.

Related errors

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