{"record":{"id":"993544db47f8285d","repo":"headroomlabs-ai/headroom","slug":"cmd-0-not-found-in-path-install-it-or-use-a","errorCode":null,"errorMessage":"`{cmd[0]}` not found in PATH. Install it or use a different backend with --model <litellm-model-name>.","messagePattern":"`(.+?)` not found in PATH\\. Install it or use a different backend with --model <litellm-model-name>\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"headroom/learn/analyzer.py","lineNumber":594,"sourceCode":"    prompt = _SYSTEM_PROMPT + \"\\n\\n\" + _USER_PROMPT_PREFIX + digest\n    hard_cap = _resolve_timeout_secs(\"HEADROOM_LEARN_CLI_TIMEOUT_SECS\", _CLI_TIMEOUT)\n\n    if model == \"claude-cli\":\n        idle_cap = _resolve_timeout_secs(\"HEADROOM_LEARN_CLI_IDLE_TIMEOUT_SECS\", _CLI_IDLE_TIMEOUT)\n        return _call_claude_cli_streaming(cmd, prompt, hard_cap=hard_cap, idle_cap=idle_cap)\n\n    try:\n        result = run(\n            cmd,\n            input=prompt,\n            capture_output=True,\n            text=True,\n            timeout=hard_cap,\n        )\n    except FileNotFoundError:\n        shim_cmd = _resolve_windows_cli_shim(cmd)\n        if shim_cmd is None:\n            raise RuntimeError(\n                f\"`{cmd[0]}` not found in PATH. Install it or use a different backend \"\n                \"with --model <litellm-model-name>.\"\n            ) from None\n        cmd = shim_cmd\n        try:\n            result = run(cmd, input=prompt, capture_output=True, text=True, timeout=hard_cap)\n        except FileNotFoundError:\n            raise RuntimeError(\n                f\"`{cmd[0]}` not found in PATH. Install it or use a different backend \"\n                \"with --model <litellm-model-name>.\"\n            ) from None\n    except subprocess.TimeoutExpired:\n        raise RuntimeError(\n            f\"`{' '.join(cmd)}` did not respond within {hard_cap}s. \"\n            \"Check network connectivity, raise HEADROOM_LEARN_CLI_TIMEOUT_SECS, \"\n            \"or try a different backend with --model <litellm-model-name>.\"\n        ) from None\n","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/learn/analyzer.py#L576-L612","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the binary truly resolves in the execution environment: `which claude` (or gemini/codex) in the same shell/container that runs headroom learn","Reinstall or relink the CLI (e.g. npm i -g @anthropic-ai/claude-code) ensuring its bin dir is on PATH","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"],"exampleFix":"# before\nHEADROOM_LEARN_CLI=claude headroom learn  # `claude` not on PATH at exec time\n\n# after\nexport PATH=\"$HOME/.npm-global/bin:$PATH\"\nheadroom learn\n# or: export OPENAI_API_KEY=sk-... && headroom learn --model gpt-4o","handlingStrategy":"validation","validationCode":"import os, shutil\ncli = os.environ.get('HEADROOM_LEARN_CLI', 'claude')\nif not shutil.which(cli):\n    raise SystemExit(f'{cli} not on PATH; install it, fix PATH, or use --model with an API key')","typeGuard":null,"tryCatchPattern":"try:\n    recommendations = run_learn()\nexcept RuntimeError as e:\n    if 'not found in PATH' in str(e):\n        os.environ.pop('HEADROOM_LEARN_CLI', None)  # fall back to auto-detection\n        recommendations = run_learn()\n    else:\n        raise","preventionTips":["Run `which claude` (or the chosen CLI) in the exact execution context before headroom learn","Ensure per-user npm bins are on PATH in cron/systemd/CI shells","If the CLI is optional, fall back to an API key backend on this specific error"],"tags":["path","cli","subprocess","environment"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}