{"record":{"id":"309ed149c7eee4c2","repo":"oraios/serena","slug":"failed-to-find-ocaml-lsp-server-executable-comman","errorCode":null,"errorMessage":"Failed to find ocaml-lsp-server executable.\nCommand failed: {e.cmd}\nReturn code: {e.returncode}\nStderr: {e.stderr}\n\nThis usually means ocaml-lsp-server is not installed or not in PATH.\nTry:\n  1. Check opam switch: opam switch show\n  2. Install ocaml-lsp-server: opam install ocaml-lsp-server","messagePattern":"Failed to find ocaml-lsp-server executable\\.\nCommand failed: (.+?)\nReturn code: (.+?)\nStderr: (.+?)\n\nThis usually means ocaml-lsp-server is not installed or not in PATH\\.\nTry:\n  1\\. Check opam switch: opam switch show\n  2\\. Install ocaml-lsp-server: opam install ocaml-lsp-server","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/solidlsp/language_servers/ocaml_lsp_server.py","lineNumber":208,"sourceCode":"                    [\"opam\", \"exec\", \"--\", \"which\", \"ocamllsp\"],\n                    check=True,\n                    capture_output=True,\n                    text=True,\n                    cwd=repository_root_path,\n                    **subprocess_kwargs(),\n                )\n                executable_path = result.stdout.strip()\n\n            if not os.path.exists(executable_path):\n                raise RuntimeError(f\"ocaml-lsp-server executable not found at {executable_path}\")\n\n            if platform.system() != \"Windows\":\n                os.chmod(executable_path, os.stat(executable_path).st_mode | stat.S_IEXEC)\n\n            return executable_path\n\n        except subprocess.CalledProcessError as e:\n            raise RuntimeError(\n                f\"Failed to find ocaml-lsp-server executable.\\n\"\n                f\"Command failed: {e.cmd}\\n\"\n                f\"Return code: {e.returncode}\\n\"\n                f\"Stderr: {e.stderr}\\n\\n\"\n                \"This usually means ocaml-lsp-server is not installed or not in PATH.\\n\"\n                \"Try:\\n\"\n                \"  1. Check opam switch: opam switch show\\n\"\n                \"  2. Install ocaml-lsp-server: opam install ocaml-lsp-server\\n\"\n                \"  3. Ensure opam env is activated: eval $(opam env)\"\n            )\n\n    @property\n    def supports_cross_file_references(self) -> bool:\n        \"\"\"\n        Check if this OCaml environment supports cross-file references.\n\n        Cross-file references require OCaml >= 5.2 with project-wide occurrences\n        AND ocaml-lsp-server >= 1.23.0 for reliable cross-file reference support.","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/solidlsp/language_servers/ocaml_lsp_server.py#L190-L226","documentation":"Raised when the subprocess command that locates the ocamllsp executable (e.g. `opam var lib` / `opam exec -- where ocamllsp`) exits non-zero (subprocess.CalledProcessError). The message includes the failed command, return code, and stderr, and points to likely causes: ocaml-lsp-server missing or not in PATH for the current switch.","triggerScenarios":"Instantiating OcamlLSPServer when the executable-lookup subprocess fails — opam erroring out, wrong/uninitialized switch, or ocamllsp not installed in the active switch so the lookup command returns failure.","commonSituations":"Wrong opam switch selected (one without ocaml-lsp-server); opam env not loaded in the launching shell; CI runner without the package installed; opam failing due to a corrupted root.","solutions":["Check the active switch: `opam switch show`; switch to the intended one: `opam switch <name> && eval $(opam env)`.","Install the server: `opam install ocaml-lsp-server`, then verify with `which ocamllsp`.","Load opam's environment before launching (`eval $(opam env)`) so the subprocess sees opam and its paths.","If opam itself is broken, run the failed command manually and inspect stderr; repair with `opam switch repair` or `opam init`.","Read the stderr in the error message — it names the exact command and failure."],"exampleFix":"// before (shell, no opam env in launcher)\npython -m app  # subprocess can't resolve ocamllsp\n// after\neval $(opam env)\nopam install ocaml-lsp-server\npython -m app","handlingStrategy":"try-catch","validationCode":"import shutil, subprocess\ndef can_locate_ocamllsp():\n    return shutil.which(\"opam\") is not None and subprocess.run(\n        [\"opam\", \"exec\", \"--\", \"where\", \"ocamllsp\"], capture_output=True\n    ).returncode == 0","typeGuard":null,"tryCatchPattern":"try:\n    server = OcamlLSPServer(repo_root)\nexcept RuntimeError as e:\n    if \"Failed to find ocaml-lsp-server executable\" in str(e):\n        # e.stderr names the failing opam command; fix switch/env then retry\n        run(\"eval $(opam env) && opam install ocaml-lsp-server -y\")\n        server = OcamlLSPServer(repo_root)\n    else:\n        raise","preventionTips":["Load opam env (`eval $(opam env)`) in every shell/CI step that launches the server","Pin a switch with ocaml-lsp-server installed in CI images","Run the executable-lookup command manually when troubleshooting — the error includes cmd/returncode/stderr"],"tags":["ocaml","opam","executable-not-found","subprocess","path"],"backgroundTag":"executable-not-found","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}