{"record":{"id":"fc08e826e011c2ae","repo":"headroomlabs-ai/headroom","slug":"error-openhands-not-found-in-path","errorCode":null,"errorMessage":"Error: 'openhands' not found in PATH.","messagePattern":"Error: 'openhands' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":6910,"sourceCode":"    \"\"\"Launch OpenHands CLI through Headroom proxy.\n\n    \\b\n    Sets OPENAI_BASE_URL / ANTHROPIC_BASE_URL to route OpenHands' API calls\n    through Headroom. Nothing is written to disk, so there is nothing to undo.\n\n    \\b\n    Examples:\n        headroom wrap openhands                # Start proxy + openhands\n        headroom wrap openhands -- --task ...  # Pass args to openhands\n    \"\"\"\n    if prepare_only:\n        return\n\n    openhands_bin = shutil.which(\"openhands\")\n    if not openhands_bin:\n        click.echo(\"Error: 'openhands' not found in PATH.\")\n        click.echo(\"Install OpenHands: https://docs.all-hands.dev/\")\n        raise SystemExit(1)\n\n    env = os.environ.copy()\n    openai_base = f\"http://127.0.0.1:{port}/v1\"\n    anthropic_base = _claude_proxy_base_url(port)\n    env[\"OPENAI_BASE_URL\"] = openai_base\n    env[\"OPENAI_API_BASE\"] = openai_base\n    env[\"ANTHROPIC_BASE_URL\"] = anthropic_base\n    # Also set LLM_BASE_URL for OpenHands' generic LLM provider config.\n    env[\"LLM_BASE_URL\"] = openai_base\n    env_vars_display = [\n        f\"OPENAI_BASE_URL={openai_base}\",\n        f\"ANTHROPIC_BASE_URL={anthropic_base}\",\n        f\"LLM_BASE_URL={openai_base}\",\n    ]\n    _launch_tool(\n        binary=openhands_bin,\n        args=openhands_args,\n        env=env,","sourceCodeStart":6892,"sourceCodeEnd":6928,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L6892-L6928","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install OpenHands per https://docs.all-hands.dev/ (e.g. `pip install openhands-ai` in the environment you run headroom from)","Activate the virtualenv/conda env where OpenHands was installed, or add its bin directory to PATH","Verify with `which openhands` / `openhands --version` before retrying `headroom wrap openhands`","If you only want proxy config prepared without launching, use `headroom wrap openhands --prepare-only` which skips this check"],"exampleFix":"# before (openhands installed in ~/.local/bin but PATH missing it)\nheadroom wrap openhands\n# Error: 'openhands' not found in PATH.\n\n# after\nexport PATH=\"$HOME/.local/bin:$PATH\"\nwhich openhands && headroom wrap openhands","handlingStrategy":"validation","validationCode":"import shutil\n\nif shutil.which(\"openhands\") is None:\n    raise SystemExit(\n        \"openhands not on PATH — install from https://docs.all-hands.dev/ \"\n        \"or activate the venv containing it\"\n    )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check tool availability with shutil.which before invoking headroom wrap in scripts","Pin wrap commands inside the same virtualenv where the wrapped tool is installed","Use --prepare-only when you only need proxy config, not a launch"],"tags":["cli","path","dependency","openhands","wrap"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}