headroomlabs-ai/headroom · error · SystemExit

Error: 'openhands' not found in PATH.

Error message

Error: 'openhands' not found in PATH.

What it means

Thrown by `headroom wrap openhands` when shutil.which('openhands') returns None, i.e. the OpenHands CLI executable is not resolvable on PATH. The command refuses to start the proxy+tool pairing and exits with SystemExit(1) after printing install docs. It is a pre-flight check so the proxy never launches without the wrapped tool.

Source

Thrown at headroom/cli/wrap.py:6910

    """Launch OpenHands CLI through Headroom proxy.

    \b
    Sets OPENAI_BASE_URL / ANTHROPIC_BASE_URL to route OpenHands' API calls
    through Headroom. Nothing is written to disk, so there is nothing to undo.

    \b
    Examples:
        headroom wrap openhands                # Start proxy + openhands
        headroom wrap openhands -- --task ...  # Pass args to openhands
    """
    if prepare_only:
        return

    openhands_bin = shutil.which("openhands")
    if not openhands_bin:
        click.echo("Error: 'openhands' not found in PATH.")
        click.echo("Install OpenHands: https://docs.all-hands.dev/")
        raise SystemExit(1)

    env = os.environ.copy()
    openai_base = f"http://127.0.0.1:{port}/v1"
    anthropic_base = _claude_proxy_base_url(port)
    env["OPENAI_BASE_URL"] = openai_base
    env["OPENAI_API_BASE"] = openai_base
    env["ANTHROPIC_BASE_URL"] = anthropic_base
    # Also set LLM_BASE_URL for OpenHands' generic LLM provider config.
    env["LLM_BASE_URL"] = openai_base
    env_vars_display = [
        f"OPENAI_BASE_URL={openai_base}",
        f"ANTHROPIC_BASE_URL={anthropic_base}",
        f"LLM_BASE_URL={openai_base}",
    ]
    _launch_tool(
        binary=openhands_bin,
        args=openhands_args,
        env=env,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install OpenHands per https://docs.all-hands.dev/ (e.g. `pip install openhands-ai` in the environment you run headroom from)
2. Activate the virtualenv/conda env where OpenHands was installed, or add its bin directory to PATH
3. Verify with `which openhands` / `openhands --version` before retrying `headroom wrap openhands`
4. If you only want proxy config prepared without launching, use `headroom wrap openhands --prepare-only` which skips this check

Example fix

# before (openhands installed in ~/.local/bin but PATH missing it)
headroom wrap openhands
# Error: 'openhands' not found in PATH.

# after
export PATH="$HOME/.local/bin:$PATH"
which openhands && headroom wrap openhands

import shutil

if shutil.which("openhands") is None:
    raise SystemExit(
        "openhands not on PATH — install from https://docs.all-hands.dev/ "
        "or activate the venv containing it"
    )

When it happens

Trigger: Running `headroom wrap openhands` (or `headroom wrap openhands -- --task ...`) on a machine where the `openhands` binary is not installed or its install directory (e.g. a pipx/venv bin dir, ~/.local/bin) is not on PATH. Note `--prepare-only` short-circuits before this check and never raises it.

Common situations: OpenHands installed inside a virtual environment that is not activated; installed via Docker only (no local binary); shell PATH not reloaded after install; typo'd binary name in scripts or CI.

Related errors

• Error: 'opencode' not found in PATH.
• Error: 'omp' not found in PATH.
• {_WRAP_PROXY_TIMEOUT_ENV} must be a positive integer number
• Error: 'claude' not found in PATH.
• Error: 'copilot' not found in PATH.

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