headroomlabs-ai/headroom · error · SystemExit

Error: 'goose' not found in PATH.

Error message

Error: 'goose' not found in PATH.

What it means

Before wrapping Block's Goose, Headroom resolves the `goose` binary with shutil.which('goose'). If missing, it prints this error with the goose docs URL and raises SystemExit(1) before configuring the OpenAI/Anthropic base URLs (http://127.0.0.1:<port>/v1) or starting the proxy. Guarded by the prepare_only early return.

Source

Thrown at headroom/cli/wrap.py:6821

    \b
    Uninstall: there is no ``headroom unwrap goose`` subcommand — nothing is
    written to the project.

    \b
    Examples:
        headroom wrap goose                          # Start proxy + goose
        headroom wrap goose -- session               # Start a Goose session
        headroom wrap goose -- --provider anthropic  # Pass args to goose
    """
    if prepare_only:
        return

    goose_bin = shutil.which("goose")
    if not goose_bin:
        click.echo("Error: 'goose' not found in PATH.")
        click.echo("Install Goose: https://block.github.io/goose/")
        raise SystemExit(1)

    # Goose accepts OpenAI- and Anthropic-compatible providers; route both.
    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
    env_vars_display = [
        f"OPENAI_BASE_URL={openai_base}",
        f"ANTHROPIC_BASE_URL={anthropic_base}",
    ]

    _launch_tool(
        binary=goose_bin,
        args=goose_args,
        env=env,
        port=port,

View on GitHub (pinned to 322425c43b)

Solutions

1. Install Goose per https://block.github.io/goose/
2. For cargo installs, ensure PATH includes ~/.cargo/bin: export PATH="$HOME/.cargo/bin:$PATH"
3. Verify with `which goose && goose --version` in the same shell before retrying
4. Use --prepare-only if you only want proxy/config preparation without launching Goose

Example fix

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

# after
# install per block.github.io/goose, then:
export PATH="$HOME/.cargo/bin:$PATH"
which goose && headroom wrap goose -- session

import shutil

if not shutil.which("goose"):
    raise SystemExit("Install Goose first: https://block.github.io/goose/")

import shutil

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

When it happens

Trigger: Running `headroom wrap goose` (without --prepare-only) on a machine where Goose is not installed or its binary location (typically a cargo bin dir like ~/.cargo/bin, since Goose is a Rust tool) is not on the current shell's PATH.

Common situations: Goose not installed; installed with cargo but ~/.cargo/bin missing from PATH in IDE/launchd shells; installed via the desktop app whose CLI shim isn't linked; CI images without goose.

Related errors

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

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