{"record":{"id":"c67c631ec9c3b985","repo":"headroomlabs-ai/headroom","slug":"error-codex-not-found-in-path","errorCode":null,"errorMessage":"Error: 'codex' not found in PATH.","messagePattern":"Error: 'codex' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":5821,"sourceCode":"        ensure_proxy_dependencies()\n\n    if prepare_only:\n        _prepare_codex_wrap_state(\n            port=port,\n            no_mcp=no_mcp,\n            no_tokensave=no_tokensave,\n            serena=serena,\n            no_serena=no_serena,\n            memory=memory,\n            verbose=verbose,\n        )\n        return\n\n    codex_bin = shutil.which(\"codex\")\n    if not codex_bin:\n        click.echo(\"Error: 'codex' not found in PATH.\")\n        click.echo(\"Install Codex CLI: npm install -g @openai/codex\")\n        raise SystemExit(1)\n\n    active_codex_home = _codex_home_dir()\n    _offer_dangling_codex_recovery(active_codex_home)\n    _prepare_codex_wrap_state(\n        port=port,\n        no_mcp=no_mcp,\n        no_tokensave=no_tokensave,\n        serena=serena,\n        no_serena=no_serena,\n        memory=memory,\n        verbose=verbose,\n        persistent_routing=False,\n    )\n\n    env, env_vars_display = _build_codex_launch_env(port, os.environ)\n    env[\"CODEX_HOME\"] = str(active_codex_home)\n\n    def configure_codex_launch(","sourceCodeStart":5803,"sourceCodeEnd":5839,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L5803-L5839","documentation":"Before wrapping OpenAI Codex CLI, Headroom resolves the `codex` binary with shutil.which('codex'). If it is not on PATH, it prints this error, suggests the npm install command, and raises SystemExit(1) before touching Codex config (~/.codex/config.toml) or starting the proxy. An earlier branch delegates to shared preparation when prepare_only is set, bypassing this check.","triggerScenarios":"Running `headroom wrap codex` (without --prepare-only) where `codex` is not installed or not resolvable on PATH: never installed, installed under a node version manager's bin dir absent from PATH, or installed via a package that names the binary differently.","commonSituations":"nvm/fnm shells without `nvm use` loading the version that owns the global install; installing @openai/codex for a different user; CI images with headroom but not codex; stale shell after install.","solutions":["Install Codex CLI: npm install -g @openai/codex","Run `nvm use <version>` (or ensure the npm global bin dir is on PATH) in the launching shell","Verify resolution first: `which codex && codex --version`","Use `headroom wrap codex --prepare-only` if you only want config/MCP preparation without launching Codex"],"exampleFix":"# before\nheadroom wrap codex\n# Error: 'codex' not found in PATH.\n\n# after\nnpm install -g @openai/codex\nwhich codex && headroom wrap codex","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not shutil.which(\"codex\"):\n    raise SystemExit(\"Install Codex CLI first: npm install -g @openai/codex\")","typeGuard":"import shutil\n\ndef codex_available() -> bool:\n    \"\"\"True when the OpenAI Codex CLI is resolvable on PATH.\"\"\"\n    return shutil.which(\"codex\") is not None","tryCatchPattern":null,"preventionTips":["Run `which codex && codex --version` before wrapping","With nvm, `nvm use` the node version that owns the global install","Use --prepare-only when you only need config preparation"],"tags":["path","installation","codex","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}