{"record":{"id":"9f8705ec4d0c518c","repo":"headroomlabs-ai/headroom","slug":"error-grok-not-found-in-path","errorCode":null,"errorMessage":"Error: 'grok' not found in PATH.","messagePattern":"Error: 'grok' not found in PATH\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"headroom/cli/wrap.py","lineNumber":6399,"sourceCode":"\n    _setup_coding_compressor(\n        GrokRegistrar(),\n        serena_context=\"grok\",\n        serena=serena,\n        no_serena=no_serena,\n        no_tokensave=no_tokensave,\n        verbose=verbose,\n        force=True,\n    )\n\n    if prepare_only:\n        return\n\n    grok_bin = shutil.which(\"grok\")\n    if not grok_bin:\n        click.echo(\"Error: 'grok' not found in PATH.\")\n        click.echo(\"Install Grok CLI: https://docs.x.ai/docs/grok-cli\")\n        raise SystemExit(1)\n\n    env, env_vars_display = _build_grok_launch_env(\n        port, os.environ, project=_project_name_from_cwd()\n    )\n\n    _launch_tool(\n        binary=grok_bin,\n        args=grok_args,\n        env=env,\n        port=port,\n        no_proxy=no_proxy,\n        tool_label=\"GROK\",\n        env_vars_display=env_vars_display,\n        learn=learn,\n        memory=memory,\n        agent_type=\"grok\",\n        code_graph=code_graph,\n        backend=backend,","sourceCodeStart":6381,"sourceCodeEnd":6417,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/cli/wrap.py#L6381-L6417","documentation":"Before wrapping Grok CLI, Headroom resolves the `grok` binary with shutil.which('grok'). If missing, it prints this error with the x.ai docs URL and raises SystemExit(1). This happens after shared wrap-state preparation (_prepare_* with force=True) but before building the Grok launch environment, so some wrap state may already be prepared when this fires.","triggerScenarios":"Running `headroom wrap grok` (without --prepare-only) where the `grok` executable is not installed or not on PATH — e.g. Grok CLI not installed, or installed under ~/.local/bin / a package-manager bin dir absent from the launching shell's PATH.","commonSituations":"Grok CLI not yet installed on the machine; installed via npm but the shell doesn't include the global bin dir; stale shell after install; CI containers with headroom but not grok.","solutions":["Install Grok CLI per https://docs.x.ai/docs/grok-cli","Verify resolution: `which grok && grok --version` in the same shell","Export the install bin dir (e.g. export PATH=\"$HOME/.local/bin:$PATH\") and `hash -r` before retrying","Use --prepare-only if you only need the proxy and config prepared without launching Grok"],"exampleFix":"# before\nheadroom wrap grok\n# Error: 'grok' not found in PATH.\n\n# after\n# install per docs.x.ai/docs/grok-cli, then:\nwhich grok && headroom wrap grok","handlingStrategy":"type-guard","validationCode":"import shutil\n\nif not shutil.which(\"grok\"):\n    raise SystemExit(\"Install Grok CLI first: https://docs.x.ai/docs/grok-cli\")","typeGuard":"import shutil\n\ndef grok_available() -> bool:\n    \"\"\"True when the Grok CLI binary is resolvable on PATH.\"\"\"\n    return shutil.which(\"grok\") is not None","tryCatchPattern":null,"preventionTips":["Verify `which grok` before wrapping","Add the Grok install bin dir to PATH and reload the shell","In CI, install grok in the same image step as headroom"],"tags":["path","installation","grok","xai","cli","headroom"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}