github/copilot-sdk · critical · RuntimeError

Copilot CLI not found at

Error message

Copilot CLI not found at {original_path}

What it means

Before spawning the Copilot CLI subprocess the SDK verifies the resolved cli_path exists on disk. If the path does not exist and shutil.which() cannot find it on PATH, this RuntimeError is raised naming the original path.

Solutions

1. Install the Copilot CLI (npm install -g @github/copilot or the official installer) so it exists on PATH
2. Fix the cli_path in ConnectionOptions to the actual binary location (verify with `which copilot`)
3. Ensure PATH includes the CLI's install directory in non-interactive environments (containers, cron, systemd)
4. Check file permissions — the file must be executable, not just present

Example fix

// before
client = Client(ConnectionOptions(cli_path="~/bin/copilot"))  # does not exist
// after
cli = shutil.which("copilot") or "/usr/local/bin/copilot"
assert os.path.exists(cli)
client = Client(ConnectionOptions(cli_path=cli))

import os, shutil
cli = opts.cli_path or "copilot"
if not os.path.exists(cli):
    cli = shutil.which(cli)
if cli is None:
    raise SystemExit("Copilot CLI not installed; install it or fix cli_path")

try:
    client = Client(opts)
    await client.start()
except RuntimeError as e:
    if "Copilot CLI not found" in str(e):
        raise SystemExit("Install the Copilot CLI or set ConnectionOptions.cli_path")
    raise

When it happens

Trigger: Creating a Client with ConnectionOptions(cli_path=...) pointing to a nonexistent binary, or relying on the default resolution when no Copilot CLI is installed or on PATH.

Common situations: Fresh machines/CI containers without the Copilot CLI installed; PATH not set up in cron/container environments; typos or renamed binaries in cli_path; CLI uninstalled after a config referenced it.

Related errors

• In-process runtime library not found next to
• joinSession() is intended for extensions running as child…
• Copilot runtime wrapper not found at
• Invalid . Expected 'inprocess', 'stdio', or unset.
• env is not supported with…

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

Appendix: source

Thrown at python/copilot/client.py:4339

        """
        if isinstance(self._connection, InProcessRuntimeConnection):
            await self._start_inprocess_ffi()
            return

        assert isinstance(self._connection, ChildProcessRuntimeConnection)
        conn = self._connection
        opts = self._options
        use_stdio = isinstance(conn, StdioRuntimeConnection)
        tcp_port = conn.port if isinstance(conn, TcpRuntimeConnection) else 0

        cli_path = conn.path
        assert cli_path is not None  # resolved in __init__

        # Verify CLI exists
        if not os.path.exists(cli_path):
            original_path = cli_path
            if (cli_path := shutil.which(cli_path)) is None:
                raise RuntimeError(f"Copilot CLI not found at {original_path}")

        # Start with user-provided args, then add SDK-managed args
        args = list(conn.args) + [
            "--headless",
            "--no-auto-update",
            "--log-level",
            opts.log_level,
        ]

        # Add auth-related flags
        if opts.github_token:
            args.extend(["--auth-token-env", "COPILOT_SDK_AUTH_TOKEN"])
        if not opts.use_logged_in_user:
            args.append("--no-auto-login")

        if opts.session_idle_timeout_seconds is not None and opts.session_idle_timeout_seconds > 0:
            args.extend(["--session-idle-timeout", str(opts.session_idle_timeout_seconds)])

View on GitHub (pinned to cd8cf15dc3)