headroomlabs-ai/headroom · error · SystemExit

Error: {e}

Error message

Error: {e}

What it means

In `headroom learn`, the LLM model id is resolved early — either from the --model option or by _detect_default_model(). If detection fails (no credentials/config from which a default model can be inferred), the RuntimeError message is echoed as 'Error: {e}' and the command exits 1. This is a deliberate fail-fast so the (expensive) session analysis never starts without a usable model.

Source

Thrown at headroom/cli/learn.py:207

        if ignored:
            verb = "is" if len(ignored) == 1 else "are"
            click.echo(f"Note: {', '.join(ignored)} {verb} ignored with --verbosity.")
        _run_verbosity(
            project=project,
            analyze_all=analyze_all,
            apply=apply,
            agent=agent,
            llm_judge=llm_judge,
            model=model,
        )
        return

    # Resolve model early to fail fast with a clear message
    try:
        resolved_model = model or _detect_default_model()
    except RuntimeError as e:
        click.echo(f"Error: {e}")
        raise SystemExit(1) from None

    analyzer = SessionAnalyzer(model=resolved_model)

    # Determine which agents to scan
    agent_configs: list[tuple[str, LearnPlugin]] = []

    if agent == "auto":
        detected = auto_detect_plugins()
        if not detected:
            click.echo("No coding agent data found.")
            return
        click.echo(f"Detected agents: {', '.join(p.display_name for p in detected)}")
        agent_configs = [(p.name, p) for p in detected]
    else:
        selected = get_plugin(agent)
        agent_configs = [(selected.name, selected)]

    total_projects = 0

View on GitHub (pinned to 322425c43b)

Solutions

1. Pass the model explicitly: headroom learn --model claude-sonnet-4-5 (or your provider's id)
2. Export the credentials _detect_default_model looks for (e.g. ANTHROPIC_API_KEY / OPENAI_API_KEY) and retry
3. Run headroom's config/init command for your provider so a default model is recorded
4. Read the RuntimeError text echoed after 'Error:' — it names the specific thing detection lacked

Example fix

# before
$ headroom learn
# Error: no default model detected; set --model or configure credentials

# after
$ export ANTHROPIC_API_KEY=sk-ant-...
$ headroom learn --model claude-sonnet-4-5

import os
model = os.environ.get("HEADROOM_MODEL") or (
    "claude-sonnet-4-5" if os.environ.get("ANTHROPIC_API_KEY") else None
)
if model is None and not os.environ.get("OPENAI_API_KEY"):
    raise SystemExit("no model resolvable — pass --model or export an API key")

try:
    subprocess.run(["headroom", "learn", "--model", model, ...], check=True)
except subprocess.CalledProcessError as e:
    if e.returncode == 1 and "Error:" in (e.stdout or ""):
        # model detection failed upstream — surface the message, do not retry blind
        print(e.stdout)

When it happens

Trigger: Running `headroom learn` (or `headroom learn analyze`) with no --model while _detect_default_model() cannot find a default — e.g. no ANTHROPIC_API_KEY / OPENAI_API_KEY / agent config exposing a model, or no supported agent on the machine.

Common situations: Fresh machines or CI with no API keys in env; keys present but in a shell file not sourced into this session; headroom config that has never been initialized; detection supporting only specific providers.

Related errors

• {_WRAP_PROXY_TIMEOUT_ENV} must be a positive integer number
• HEADROOM_LEARN_CLI={cli_override!r} is not a supported CLI.
• No LLM API key found. headroom learn needs one of: export
• `{' '.join(cmd)}` did not respond within {hard_cap}s. Check
• `{' '.join(cmd)}` produced no output for {idle_cap}s. Check

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