{"record":{"id":"cdf0a3ca302f44d7","repo":"github/copilot-sdk","slug":"in-process-ffi-runtime-library-not-found-at-full","errorCode":null,"errorMessage":"In-process FFI runtime library not found at '{full_library_path}'.","messagePattern":"In-process FFI runtime library not found at '(.+?)'\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/_ffi_runtime_host.py","lineNumber":387,"sourceCode":"    def process(self) -> _FfiProcessAdapter:\n        \"\"\"The ``subprocess.Popen``-shaped adapter for :class:`JsonRpcClient`.\"\"\"\n        return self._process\n\n    @staticmethod\n    def create(\n        library_path: str,\n        cli_entrypoint: str | None = None,\n        environment: dict[str, str] | None = None,\n        args: Sequence[str] = (),\n    ) -> FfiRuntimeHost:\n        \"\"\"Load the runtime cdylib and prepare the host.\n\n        Raises:\n            RuntimeError: If the native runtime library cannot be found.\n        \"\"\"\n        full_library_path = str(Path(library_path).resolve())\n        if not Path(full_library_path).is_file():\n            raise RuntimeError(\n                f\"In-process FFI runtime library not found at '{full_library_path}'.\"\n            )\n        full_entrypoint = (\n            str(Path(cli_entrypoint).resolve()) if cli_entrypoint is not None else None\n        )\n        return FfiRuntimeHost(full_library_path, full_entrypoint, environment, args)\n\n    def _build_argv(self) -> bytes:\n        if self._cli_entrypoint is None:\n            argv: list[str] = []\n        elif self._cli_entrypoint.lower().endswith(\".js\"):\n            argv = [\"node\", self._cli_entrypoint, \"--embedded-host\", \"--no-auto-update\"]\n        else:\n            argv = [self._cli_entrypoint, \"--embedded-host\", \"--no-auto-update\"]\n        argv.extend(self._extra_args)\n        return json.dumps(argv).encode(\"utf-8\")\n\n    def _build_env(self) -> bytes | None:","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/_ffi_runtime_host.py#L369-L405","documentation":"FfiRuntimeHost.create validates that the resolved native runtime library path exists and is a regular file before constructing the host. If the file is missing it raises this error rather than letting ctypes fail with a lower-level message.","triggerScenarios":"Calling FfiRuntimeHost.create(library_path=...) with a path that does not exist or is a directory — typically a wrong cache path, an uninstall that removed runtime.node, or a platform key that was never downloaded.","commonSituations":"Cache directory cleaned between runs; calling create() before get_or_download_cli()/ensure_runtime_library(); typo'd or relative path that does not resolve to an existing file.","solutions":["Call get_or_download_cli()/ensure_runtime_library() first so the runtime library is downloaded to the expected path.","Print and verify the resolved library_path; fix typos or stale configuration pointing at a removed install.","Reinstall/re-download the Copilot runtime if the cache was deleted.","Confirm the path is a file, not a directory."],"exampleFix":"# before\nhost = FfiRuntimeHost.create(library_path=\"~/.cache/copilot/runtime.node\")\n# after\nfrom pathlib import Path\nlib = get_or_download_cli()  # ensure runtime exists\nhost = FfiRuntimeHost.create(library_path=str(Path(lib).expanduser().resolve()))","handlingStrategy":"validation","validationCode":"from pathlib import Path\nlib = Path(library_path).expanduser().resolve()\nif not lib.is_file():\n    get_or_download_cli()  # ensure runtime present","typeGuard":"def has_runtime_library(path: str) -> bool:\n    p = Path(path).expanduser().resolve()\n    return p.is_file()","tryCatchPattern":"try:\n    host = FfiRuntimeHost.create(library_path)\nexcept RuntimeError as e:\n    if \"not found\" in str(e):\n        get_or_download_cli()\n        host = FfiRuntimeHost.create(library_path)","preventionTips":["Always call get_or_download_cli()/ensure_runtime_library() before create().","Use cache path helpers instead of hardcoding runtime paths.","Verify the cache directory exists after container image builds."],"tags":["ffi","file-not-found","runtime"],"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-16T04:17:20.429Z"}