{"record":{"id":"cf44acd66af1c993","repo":"headroomlabs-ai/headroom","slug":"error-copilot-byok-mode-requires-a-provider-api-k","errorCode":null,"errorMessage":"Error: Copilot BYOK mode requires a provider API key. `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's Copilot API and routes requests directly to the model provider through the Headroom proxy. A GitHub Copilot subscription alone is not sufficient. Set one of: export {src}=sk-... export COPILOT_PROVIDER_API_KEY=sk-...","messagePattern":"Error: Copilot BYOK mode requires a provider API key\\. `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's Copilot API and routes requests directly to the model provider through the Headroom proxy\\. A GitHub Copilot subscription alone is not sufficient\\. Set one of: export (.+?)=sk-\\.\\.\\. export COPILOT_PROVIDER_API_KEY=sk-\\.\\.\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":5442,"sourceCode":"            port=port,\n            provider_type=effective_provider_type,\n            wire_api=wire_api,\n            environ=env,\n            project=_project_name_from_cwd(),\n        )\n\n        if not env.get(\"COPILOT_PROVIDER_API_KEY\"):\n            src = _copilot_provider_key_source(effective_provider_type)\n            click.echo(\n                f\"\\n  Error: Copilot BYOK mode requires a provider API key.\\n\"\n                f\"  `headroom wrap copilot` uses Copilot's BYOK mode, which bypasses GitHub's\\n\"\n                f\"  Copilot API and routes requests directly to the model provider through the\\n\"\n                f\"  Headroom proxy. A GitHub Copilot subscription alone is not sufficient.\\n\\n\"\n                f\"  Set one of:\\n\"\n                f\"    export {src}=sk-...          # recommended\\n\"\n                f\"    export COPILOT_PROVIDER_API_KEY=sk-...  # also works\\n\"\n            )\n            raise SystemExit(1)\n\n    if not subscription and not _copilot_model_configured(copilot_args, env):\n        # Distinguish between \"--model auto\" (wrong model for BYOK) and\n        # genuinely missing model (no --model flag at all).\n        raw_model = _copilot_model_from_args(copilot_args, env)\n        if _is_auto_model(raw_model):\n            click.echo(\n                \"  Error: '--model auto' is not supported in Copilot BYOK mode.\\n\"\n                \"  BYOK routes to an external provider (Anthropic/OpenAI) which\\n\"\n                \"  does not recognise 'auto' as a model name — the request will\\n\"\n                \"  fail with a 400 error.\\n\"\n                \"  Options:\\n\"\n                \"    • Use a concrete model: --model gpt-4o\\n\"\n                \"    • Use subscription mode for native auto-routing:\\n\"\n                \"      headroom wrap copilot --subscription -- --model auto\"\n            )\n            raise SystemExit(1)\n        else:","sourceCodeStart":5424,"sourceCodeEnd":5460,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L5424-L5460","documentation":"`headroom wrap copilot` uses Copilot's bring-your-own-key (BYOK) mode: requests bypass GitHub's Copilot API and route directly to the model provider (Anthropic/OpenAI) through the Headroom proxy. This error fires when neither the provider-specific key (named by _copilot_provider_key_source for the effective provider type) nor the generic COPILOT_PROVIDER_API_KEY is set in the environment. A GitHub Copilot subscription alone cannot authenticate BYOK traffic, so Headroom aborts before launching.","triggerScenarios":"Running `headroom wrap copilot` without --subscription while COPILOT_PROVIDER_API_KEY and the provider-specific key (e.g. ANTHROPIC_API_KEY / OPENAI_API_KEY, depending on effective_provider_type from --backend/--provider-type/HEADROOM_BACKEND) are all unset or empty in the environment.","commonSituations":"Users with an active Copilot subscription assuming it suffices; keys defined in a .env file that the shell never sourced; keys set in a different terminal or launcher (IDE) environment; switching provider backends without exporting the matching key.","solutions":["Export the provider-specific key as printed in the message, e.g. export ANTHROPIC_API_KEY=sk-... (recommended)","Or export the generic fallback: export COPILOT_PROVIDER_API_KEY=sk-...","Or use subscription mode instead of BYOK: headroom wrap copilot --subscription","Verify the key is non-empty in the launching shell: echo -n \"${COPILOT_PROVIDER_API_KEY:-}\" | wc -c"],"exampleFix":"# before\nheadroom wrap copilot            # subscription only, no provider key\n# Error: Copilot BYOK mode requires a provider API key.\n\n# after\nexport ANTHROPIC_API_KEY=sk-ant-...\nheadroom wrap copilot -- --model claude-sonnet-4","handlingStrategy":"validation","validationCode":"import os\n\ndef byok_key_present(provider_type: str) -> bool:\n    specific = {\n        \"anthropic\": \"ANTHROPIC_API_KEY\",\n        \"openai\": \"OPENAI_API_KEY\",\n    }.get(provider_type, \"\")\n    return bool(os.environ.get(specific) or os.environ.get(\"COPILOT_PROVIDER_API_KEY\"))\n\nassert byok_key_present(\"anthropic\"), \"Set ANTHROPIC_API_KEY or COPILOT_PROVIDER_API_KEY for BYOK\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Export the provider key in the exact shell that runs headroom wrap copilot","Or explicitly choose --subscription when you have no provider key","Source your .env in the launching shell or use an env manager (direnv)"],"tags":["authentication","api-key","byok","github-copilot","environment-variables","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}