{"record":{"id":"9ea3f0c583f9c5a0","repo":"github/copilot-sdk","slug":"copilot-cli-not-found-at-original-path","errorCode":null,"errorMessage":"Copilot CLI not found at {original_path}","messagePattern":"Copilot CLI not found at (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/copilot/client.py","lineNumber":4339,"sourceCode":"        \"\"\"\n        if isinstance(self._connection, InProcessRuntimeConnection):\n            await self._start_inprocess_ffi()\n            return\n\n        assert isinstance(self._connection, ChildProcessRuntimeConnection)\n        conn = self._connection\n        opts = self._options\n        use_stdio = isinstance(conn, StdioRuntimeConnection)\n        tcp_port = conn.port if isinstance(conn, TcpRuntimeConnection) else 0\n\n        cli_path = conn.path\n        assert cli_path is not None  # resolved in __init__\n\n        # Verify CLI exists\n        if not os.path.exists(cli_path):\n            original_path = cli_path\n            if (cli_path := shutil.which(cli_path)) is None:\n                raise RuntimeError(f\"Copilot CLI not found at {original_path}\")\n\n        # Start with user-provided args, then add SDK-managed args\n        args = list(conn.args) + [\n            \"--headless\",\n            \"--no-auto-update\",\n            \"--log-level\",\n            opts.log_level,\n        ]\n\n        # Add auth-related flags\n        if opts.github_token:\n            args.extend([\"--auth-token-env\", \"COPILOT_SDK_AUTH_TOKEN\"])\n        if not opts.use_logged_in_user:\n            args.append(\"--no-auto-login\")\n\n        if opts.session_idle_timeout_seconds is not None and opts.session_idle_timeout_seconds > 0:\n            args.extend([\"--session-idle-timeout\", str(opts.session_idle_timeout_seconds)])\n","sourceCodeStart":4321,"sourceCodeEnd":4357,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L4321-L4357","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the Copilot CLI (npm install -g @github/copilot or the official installer) so it exists on PATH","Fix the cli_path in ConnectionOptions to the actual binary location (verify with `which copilot`)","Ensure PATH includes the CLI's install directory in non-interactive environments (containers, cron, systemd)","Check file permissions — the file must be executable, not just present"],"exampleFix":"// before\nclient = Client(ConnectionOptions(cli_path=\"~/bin/copilot\"))  # does not exist\n// after\ncli = shutil.which(\"copilot\") or \"/usr/local/bin/copilot\"\nassert os.path.exists(cli)\nclient = Client(ConnectionOptions(cli_path=cli))","handlingStrategy":"validation","validationCode":"import os, shutil\ncli = opts.cli_path or \"copilot\"\nif not os.path.exists(cli):\n    cli = shutil.which(cli)\nif cli is None:\n    raise SystemExit(\"Copilot CLI not installed; install it or fix cli_path\")","typeGuard":null,"tryCatchPattern":"try:\n    client = Client(opts)\n    await client.start()\nexcept RuntimeError as e:\n    if \"Copilot CLI not found\" in str(e):\n        raise SystemExit(\"Install the Copilot CLI or set ConnectionOptions.cli_path\")\n    raise","preventionTips":["Verify `which copilot` succeeds in the target environment before running","Install the CLI in your container/CI image explicitly","Use absolute verified paths in cli_path for non-interactive environments","Check PATH setup in cron/systemd/container contexts"],"tags":["file-not-found","cli","environment","path","python"],"backgroundTag":"command-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"}