headroomlabs-ai/headroom · error · RuntimeError

`{cmd[0]}` not found in PATH. Install it or use a different

Error message

`{cmd[0]}` not found in PATH. Install it or use a different backend with --model <litellm-model-name>.

What it means

First FileNotFoundError handler in the generic CLI runner: subprocess.run(cmd, input=prompt, ...) raised FileNotFoundError because the CLI executable (cmd[0]) is not on PATH. Before giving up, the code tries _resolve_windows_cli_shim(cmd) — a Windows shim workaround (e.g. .cmd/.bat wrappers); this raise is the no-shim-available terminal error telling you to install the CLI or switch backends with --model.

Source

Thrown at headroom/learn/analyzer.py:594

    prompt = _SYSTEM_PROMPT + "\n\n" + _USER_PROMPT_PREFIX + digest
    hard_cap = _resolve_timeout_secs("HEADROOM_LEARN_CLI_TIMEOUT_SECS", _CLI_TIMEOUT)

    if model == "claude-cli":
        idle_cap = _resolve_timeout_secs("HEADROOM_LEARN_CLI_IDLE_TIMEOUT_SECS", _CLI_IDLE_TIMEOUT)
        return _call_claude_cli_streaming(cmd, prompt, hard_cap=hard_cap, idle_cap=idle_cap)

    try:
        result = run(
            cmd,
            input=prompt,
            capture_output=True,
            text=True,
            timeout=hard_cap,
        )
    except FileNotFoundError:
        shim_cmd = _resolve_windows_cli_shim(cmd)
        if shim_cmd is None:
            raise RuntimeError(
                f"`{cmd[0]}` not found in PATH. Install it or use a different backend "
                "with --model <litellm-model-name>."
            ) from None
        cmd = shim_cmd
        try:
            result = run(cmd, input=prompt, capture_output=True, text=True, timeout=hard_cap)
        except FileNotFoundError:
            raise RuntimeError(
                f"`{cmd[0]}` not found in PATH. Install it or use a different backend "
                "with --model <litellm-model-name>."
            ) from None
    except subprocess.TimeoutExpired:
        raise RuntimeError(
            f"`{' '.join(cmd)}` did not respond within {hard_cap}s. "
            "Check network connectivity, raise HEADROOM_LEARN_CLI_TIMEOUT_SECS, "
            "or try a different backend with --model <litellm-model-name>."
        ) from None

View on GitHub (pinned to 322425c43b)

Solutions

1. Verify the binary truly resolves in the execution environment: `which claude` (or gemini/codex) in the same shell/container that runs headroom learn
2. Reinstall or relink the CLI (e.g. npm i -g @anthropic-ai/claude-code) ensuring its bin dir is on PATH
3. Switch backend without the CLI: export an API key and run headroom learn --model <litellm-model-name>, or unset HEADROOM_LEARN_CLI so it is not forced

Example fix

# before
HEADROOM_LEARN_CLI=claude headroom learn  # `claude` not on PATH at exec time

# after
export PATH="$HOME/.npm-global/bin:$PATH"
headroom learn
# or: export OPENAI_API_KEY=sk-... && headroom learn --model gpt-4o

import os, shutil
cli = os.environ.get('HEADROOM_LEARN_CLI', 'claude')
if not shutil.which(cli):
    raise SystemExit(f'{cli} not on PATH; install it, fix PATH, or use --model with an API key')

try:
    recommendations = run_learn()
except RuntimeError as e:
    if 'not found in PATH' in str(e):
        os.environ.pop('HEADROOM_LEARN_CLI', None)  # fall back to auto-detection
        recommendations = run_learn()
    else:
        raise

When it happens

Trigger: Backend resolution picked a CLI (via HEADROOM_LEARN_CLI or auto-detect) but the binary vanished or is not visible: shutil.which found it during resolution yet the actual spawn fails, or resolution happened on a different machine (config baked into an image). On non-Windows, _resolve_windows_cli_shim returns None so this raise fires immediately.

Common situations: PATH differs between the detection shell and the execution shell (cron, systemd, CI steps that reset env); CLI installed per-user (npm global with user prefix) but headroom learn runs as another user; CLI uninstalled after HEADROOM_LEARN_CLI was configured; Windows where the .exe needs the shim and the shim lookup also fails.

Related errors

• Proxy exited with code {proc.returncode}: {tail}
• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.
• Error: 'codex' not found in PATH.
• Error: 'aider' not found in PATH.

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