headroomlabs-ai/headroom · error · SystemExit

Error: 'aider' not found in PATH.

Error message

Error: 'aider' not found in PATH.

What it means

Before wrapping aider, Headroom resolves the `aider` binary with shutil.which('aider'). If missing, it prints this error, suggests `pip install aider-chat`, and raises SystemExit(1) before building the launch environment (_build_aider_launch_env) or starting the proxy. Guarded by the prepare_only early return.

Source

Thrown at headroom/cli/wrap.py:6037

    \b
    Sets OPENAI_API_BASE to route all API calls through Headroom.

    \b
    Examples:
        headroom wrap aider                              # Start proxy + aider
        headroom wrap aider -- --model gpt-4o            # Use GPT-4o
        headroom wrap aider -- --model claude-sonnet-4   # Use Claude
        headroom wrap aider --backend litellm-vertex --region us-central1
    """
    if prepare_only:
        return

    aider_bin = shutil.which("aider")
    if not aider_bin:
        click.echo("Error: 'aider' not found in PATH.")
        click.echo("Install aider: pip install aider-chat")
        raise SystemExit(1)

    env, env_vars_display = _build_aider_launch_env(
        port, os.environ, project=_project_name_from_cwd()
    )

    _launch_tool(
        binary=aider_bin,
        args=aider_args,
        env=env,
        port=port,
        no_proxy=no_proxy,
        tool_label="AIDER",
        env_vars_display=env_vars_display,
        learn=learn,
        memory=memory,
        agent_type="aider",
        code_graph=code_graph,
        backend=backend,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install aider: pip install aider-chat (or `python -m pip install aider-chat` for the right interpreter)
2. If using a venv, activate it before running: source .venv/bin/activate && headroom wrap aider
3. Ensure the scripts dir is on PATH: export PATH="$HOME/.local/bin:$PATH"
4. Verify with `which aider && aider --version` in the same shell

Example fix

# before
headroom wrap aider
# Error: 'aider' not found in PATH.

# after
pip install aider-chat
export PATH="$HOME/.local/bin:$PATH"
headroom wrap aider -- --model gpt-4o

import shutil

if not shutil.which("aider"):
    raise SystemExit("Install aider first: pip install aider-chat")

import shutil

def aider_available() -> bool:
    """True when the aider binary is resolvable on PATH."""
    return shutil.which("aider") is not None

When it happens

Trigger: Running `headroom wrap aider` (without --prepare-only) on a machine where aider is not installed or its install location (often a Python user-scripts dir like ~/.local/bin or a venv bin) is not on the current shell's PATH.

Common situations: aider installed inside a virtualenv that isn't activated; pip user installs landing in ~/.local/bin which is missing from PATH on minimal shell setups; aider installed via the newer `aider-install`/uv tool path with a different bin location; CI images without aider.

Related errors

• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.
• Error: 'codex' not found in PATH.
• Error: 'openclaude' not found in PATH.
• Error: 'vibe' not found in PATH.

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