github/copilot-sdk · error · RuntimeError

In-process runtime library not found next to

Error message

In-process runtime library not found next to '{explicit_cli}'.

What it means

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.

Solutions

  1. Install or copy the native runtime library next to the binary at COPILOT_CLI_PATH
  2. Point COPILOT_CLI_PATH at a full installation directory's CLI (not an isolated binary)
  3. Unset COPILOT_CLI_PATH to let the client download/locate the runtime automatically

Example fix

// before
export COPILOT_CLI_PATH=/tmp/copilot-cli   # library missing next to it
// after
export COPILOT_CLI_PATH=/opt/copilot/bin/copilot  # full install with runtime library alongside
Defensive patterns

Strategy: try-catch

Validate before calling

cli = os.environ.get("COPILOT_CLI_PATH")
if cli:
    from ._cli_download import ensure_runtime_library
    if ensure_runtime_library(cli) is None:
        raise RuntimeError(f"runtime library missing next to {cli}")

Type guard

def cli_install_complete(cli_path: str) -> bool:
    import os
    d = os.path.dirname(os.path.abspath(cli_path))
    return any(f.startswith("copilot") and (f.endswith(".so") or f.endswith(".dll") or f.endswith(".dylib")) for f in os.listdir(d))

Try / catch

try:
    client = CopilotClient(connection=RuntimeConnection.for_inprocess())
except RuntimeError as e:
    if "runtime library not found" in str(e):
        os.environ.pop("COPILOT_CLI_PATH", None)
        client = CopilotClient(connection=RuntimeConnection.for_stdio())

Prevention

When it happens

Trigger: COPILOT_CLI_PATH pointing to a standalone/copied CLI binary without the accompanying native runtime library beside it, while constructing an in-process client.

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/18394d2a5ea3809b. Report an issue: GitHub.

Appendix: source

Thrown at python/copilot/client.py:1809

        lookup = env if env is not None else os.environ
        env_cli_path = lookup.get("COPILOT_CLI_PATH")
        if env_cli_path:
            self._cli_path_source = "environment"
            return env_cli_path

        from ._cli_download import ensure_runtime_wrapper

        self._cli_path_source = "downloaded"
        return ensure_runtime_wrapper()

    def _resolve_inprocess_runtime(self) -> str:
        explicit_cli = os.environ.get("COPILOT_CLI_PATH")
        if explicit_cli:
            from ._cli_download import ensure_runtime_library

            runtime_path = ensure_runtime_library(explicit_cli)
            if runtime_path is None:
                raise RuntimeError(
                    f"In-process runtime library not found next to '{explicit_cli}'."
                )
            self._cli_path_source = "environment"
            self._inprocess_cli_entrypoint = explicit_cli
            return runtime_path

        from ._cli_download import ensure_runtime_wrapper

        wrapper_path = Path(ensure_runtime_wrapper())
        self._cli_path_source = "downloaded"
        return str(wrapper_path.with_name("runtime.node"))

    @property
    def rpc(self) -> ServerRpc:
        """Typed server-scoped RPC methods."""
        if self._rpc is None:
            raise RuntimeError("Client is not connected. Call start() first.")
        return self._rpc

View on GitHub (pinned to cd8cf15dc3)