{"record":{"id":"18394d2a5ea3809b","repo":"github/copilot-sdk","slug":"in-process-runtime-library-not-found-next-to-exp","errorCode":null,"errorMessage":"In-process runtime library not found next to '{explicit_cli}'.","messagePattern":"In-process runtime library not found next to '(.+?)'\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":1809,"sourceCode":"        lookup = env if env is not None else os.environ\n        env_cli_path = lookup.get(\"COPILOT_CLI_PATH\")\n        if env_cli_path:\n            self._cli_path_source = \"environment\"\n            return env_cli_path\n\n        from ._cli_download import ensure_runtime_wrapper\n\n        self._cli_path_source = \"downloaded\"\n        return ensure_runtime_wrapper()\n\n    def _resolve_inprocess_runtime(self) -> str:\n        explicit_cli = os.environ.get(\"COPILOT_CLI_PATH\")\n        if explicit_cli:\n            from ._cli_download import ensure_runtime_library\n\n            runtime_path = ensure_runtime_library(explicit_cli)\n            if runtime_path is None:\n                raise RuntimeError(\n                    f\"In-process runtime library not found next to '{explicit_cli}'.\"\n                )\n            self._cli_path_source = \"environment\"\n            self._inprocess_cli_entrypoint = explicit_cli\n            return runtime_path\n\n        from ._cli_download import ensure_runtime_wrapper\n\n        wrapper_path = Path(ensure_runtime_wrapper())\n        self._cli_path_source = \"downloaded\"\n        return str(wrapper_path.with_name(\"runtime.node\"))\n\n    @property\n    def rpc(self) -> ServerRpc:\n        \"\"\"Typed server-scoped RPC methods.\"\"\"\n        if self._rpc is None:\n            raise RuntimeError(\"Client is not connected. Call start() first.\")\n        return self._rpc","sourceCodeStart":1791,"sourceCodeEnd":1827,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L1791-L1827","documentation":"When using the in-process transport with COPILOT_CLI_PATH set, the client expects the native runtime library to sit next to the CLI binary; ensure_runtime_library() returns None when it cannot find it, and a RuntimeError is raised naming the explicit CLI path.","triggerScenarios":"COPILOT_CLI_PATH pointing to a standalone/copied CLI binary without the accompanying native runtime library beside it, while constructing an in-process client.","commonSituations":"Pointing COPILOT_CLI_PATH at a binary in a temp or container path that lacks the library; upgrading the CLI by copying just the executable; package layouts changed across versions so the library name/location no longer matches.","solutions":["Install or copy the native runtime library next to the binary at COPILOT_CLI_PATH","Point COPILOT_CLI_PATH at a full installation directory's CLI (not an isolated binary)","Unset COPILOT_CLI_PATH to let the client download/locate the runtime automatically"],"exampleFix":"// before\nexport COPILOT_CLI_PATH=/tmp/copilot-cli   # library missing next to it\n// after\nexport COPILOT_CLI_PATH=/opt/copilot/bin/copilot  # full install with runtime library alongside","handlingStrategy":"try-catch","validationCode":"cli = os.environ.get(\"COPILOT_CLI_PATH\")\nif cli:\n    from ._cli_download import ensure_runtime_library\n    if ensure_runtime_library(cli) is None:\n        raise RuntimeError(f\"runtime library missing next to {cli}\")","typeGuard":"def cli_install_complete(cli_path: str) -> bool:\n    import os\n    d = os.path.dirname(os.path.abspath(cli_path))\n    return any(f.startswith(\"copilot\") and (f.endswith(\".so\") or f.endswith(\".dll\") or f.endswith(\".dylib\")) for f in os.listdir(d))","tryCatchPattern":"try:\n    client = CopilotClient(connection=RuntimeConnection.for_inprocess())\nexcept RuntimeError as e:\n    if \"runtime library not found\" in str(e):\n        os.environ.pop(\"COPILOT_CLI_PATH\", None)\n        client = CopilotClient(connection=RuntimeConnection.for_stdio())","preventionTips":["Only point COPILOT_CLI_PATH at complete installations, never a copied single binary","Verify the directory contents after upgrading the CLI","Fall back to stdio transport or auto-download when the explicit path is incomplete"],"tags":["python","file-not-found","in-process","environment"],"backgroundTag":"file-not-found","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}