headroomlabs-ai/headroom · error · SystemExit

Error: '--model auto' is not supported in Copilot BYOK mode.

Error message

Error: '--model auto' is not supported in Copilot BYOK mode. BYOK routes to an external provider (Anthropic/OpenAI) which does not recognise 'auto' as a model name — the request will fail with a 400 error. Options: • Use a concrete model: --model gpt-4o • Use subscription mode for native auto-routing: headroom wrap copilot --subscription -- --model auto

What it means

In Copilot BYOK mode with no --model configured and no subscription, Headroom inspects the effective model (from args or COPILOT_MODEL / COPILOT_PROVIDER_MODEL_ID). 'auto' is a Copilot-subscription concept for native routing; BYOK forwards the model name verbatim to Anthropic/OpenAI, which reject 'auto' with a 400. Headroom fails fast with this message instead of letting the request die upstream, and suggests a concrete model or --subscription for auto-routing.

Source

Thrown at headroom/cli/wrap.py:5459

            )
            raise SystemExit(1)

    if not subscription and not _copilot_model_configured(copilot_args, env):
        # Distinguish between "--model auto" (wrong model for BYOK) and
        # genuinely missing model (no --model flag at all).
        raw_model = _copilot_model_from_args(copilot_args, env)
        if _is_auto_model(raw_model):
            click.echo(
                "  Error: '--model auto' is not supported in Copilot BYOK mode.\n"
                "  BYOK routes to an external provider (Anthropic/OpenAI) which\n"
                "  does not recognise 'auto' as a model name — the request will\n"
                "  fail with a 400 error.\n"
                "  Options:\n"
                "    • Use a concrete model: --model gpt-4o\n"
                "    • Use subscription mode for native auto-routing:\n"
                "      headroom wrap copilot --subscription -- --model auto"
            )
            raise SystemExit(1)
        else:
            click.echo(
                "  Note: Copilot BYOK requires a model. Pass `--model <name>` "
                "or set `COPILOT_MODEL` / `COPILOT_PROVIDER_MODEL_ID`."
            )

    _launch_tool(
        binary=copilot_bin,
        args=copilot_args,
        env=env,
        port=port,
        no_proxy=no_proxy,
        tool_label="COPILOT",
        env_vars_display=env_vars_display,
        learn=False,
        memory=memory,
        agent_type="copilot",
        backend=backend,

View on GitHub (pinned to 322425c43b)

Solutions

1. Pass a concrete model name the provider recognises: headroom wrap copilot -- --model gpt-4o (or claude-sonnet-4, etc.)
2. Or keep auto-routing by using subscription mode: headroom wrap copilot --subscription -- --model auto
3. Unset stale env: unset COPILOT_MODEL COPILOT_PROVIDER_MODEL_ID, or set them to a concrete provider model id
4. Check the provider's model catalog for valid names before choosing

Example fix

# before
headroom wrap copilot -- --model auto     # BYOK: 'auto' rejected

# after
headroom wrap copilot -- --model gpt-4o
# or, for auto-routing:
headroom wrap copilot --subscription -- --model auto

import os

def model_byok_safe(args: list[str]) -> bool:
    raw = next((a for a in args if a.startswith("--model")), "")
    name = raw.split("=", 1)[-1] if "=" in raw else None
    env_name = os.environ.get("COPILOT_MODEL") or os.environ.get("COPILOT_PROVIDER_MODEL_ID")
    effective = name or env_name or ""
    return effective.strip().lower() not in ("", "auto", "model-auto") or not effective

When it happens

Trigger: Running `headroom wrap copilot -- --model auto` (or with COPILOT_MODEL=auto / COPILOT_PROVIDER_MODEL_ID=auto) in BYOK mode (no --subscription), where _is_auto_model() matches the resolved name case-insensitively or via alias. Note the contrasting branch: with no model at all you only get a 'Note:', but 'auto' is a hard SystemExit(1).

Common situations: Copy-pasting subscription-mode commands into BYOK mode; COPILOT_MODEL=auto set in a shell profile from prior Copilot usage; switching from `--subscription` to BYOK without changing the model config.

Related errors

• Error: 'copilot' not found in PATH.
• Error: Copilot BYOK mode requires a provider API key. `headr
• Unknown CLI model: {model}
• No available port found in range {start_port}-{end_port - 1}
• Proxy exited with code {proc.returncode}: {tail}

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/7b3a4f668695dc3c. Report an issue: GitHub.