{"record":{"id":"0aa7d06195123429","repo":"headroomlabs-ai/headroom","slug":"error-copilot-not-found-in-path","errorCode":null,"errorMessage":"Error: 'copilot' not found in PATH.","messagePattern":"Error: 'copilot' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":5297,"sourceCode":"        headroom wrap copilot --backend anyllm --anyllm-provider groq -- --model gpt-4o\n        headroom wrap copilot --provider-type openai --wire-api responses -- --model gpt-5.4\n        headroom wrap copilot --subscription -- --model gpt-4.1\n\n    \\b\n    Copilot hosted API (--subscription and the implicit OAuth path) routes to the\n    generic host https://api.githubcopilot.com, which serves the full model set.\n    Enterprise / data-residency accounts provisioned on a dedicated host pin it\n    explicitly with GITHUB_COPILOT_API_URL (the override flows through to upstream).\n    See TESTING-copilot-subscription.md for details.\n    \"\"\"\n    copilot_bin = shutil.which(\"copilot\")\n    if not copilot_bin:\n        click.echo(\"Error: 'copilot' not found in PATH.\")\n        click.echo(\n            \"Install GitHub Copilot CLI: \"\n            \"https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli\"\n        )\n        raise SystemExit(1)\n\n    effective_backend = backend or os.environ.get(\"HEADROOM_BACKEND\")\n    if _check_proxy(port):\n        running_backend = _detect_running_proxy_backend(port)\n        if effective_backend and running_backend and effective_backend != running_backend:\n            raise click.ClickException(\n                f\"Proxy already running on port {port} with backend '{running_backend}'. \"\n                f\"Stop it or rerun with --backend {running_backend}.\"\n            )\n        effective_backend = running_backend or effective_backend\n\n    effective_provider_type = _resolve_copilot_provider_type(effective_backend, provider_type)\n    if subscription:\n        if effective_backend not in (None, \"\", \"anthropic\"):\n            raise click.ClickException(\n                \"--subscription routes to GitHub Copilot's hosted API and cannot be combined \"\n                \"with translated backends such as anyllm or litellm-*.\"\n            )","sourceCodeStart":5279,"sourceCodeEnd":5315,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L5279-L5315","documentation":"Before wrapping GitHub Copilot CLI, Headroom resolves the `copilot` binary via shutil.which('copilot'). If missing, it prints this error with the GitHub install-docs URL and raises SystemExit(1). The check happens before any backend detection, BYOK validation, or proxy startup, so nothing is modified.","triggerScenarios":"Running `headroom wrap copilot` on a machine without the GitHub Copilot CLI installed or without its install location on PATH. Subsequent logic (backend conflict detection via _detect_running_proxy_backend, provider type resolution) never runs.","commonSituations":"Copilot CLI not yet installed (it ships separately from the Copilot VS Code extension); installed under a user-local bin dir (e.g. ~/.local/bin) not on PATH in the current shell; CI images omitting the CLI; stale shell after a fresh install.","solutions":["Install GitHub Copilot CLI per the printed GitHub docs URL (set-up-copilot-cli/install-copilot-cli)","Open a new shell or `hash -r` after installing so PATH resolution picks up the binary","Verify with `which copilot` in the same shell before rerunning `headroom wrap copilot`","Ensure the install dir (often ~/.local/bin) is exported in PATH: export PATH=\"$HOME/.local/bin:$PATH\""],"exampleFix":"# before\nheadroom wrap copilot\n# Error: 'copilot' not found in PATH.\n\n# after\n# install per https://docs.github.com/.../install-copilot-cli\nexport PATH=\"$HOME/.local/bin:$PATH\"\nwhich copilot && headroom wrap copilot","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not shutil.which(\"copilot\"):\n    raise SystemExit(\"Install GitHub Copilot CLI before wrapping (see GitHub docs)\")","typeGuard":"import shutil\n\ndef copilot_available() -> bool:\n    \"\"\"True when the GitHub Copilot CLI is resolvable on PATH.\"\"\"\n    return shutil.which(\"copilot\") is not None","tryCatchPattern":null,"preventionTips":["Verify `which copilot` before `headroom wrap copilot`","Reload the shell (hash -r) after installing the CLI","Add user-local bin dirs (~/.local/bin) to PATH in shell profiles"],"tags":["path","installation","github-copilot","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}