{"record":{"id":"7b27dfb610b38b82","repo":"headroomlabs-ai/headroom","slug":"no-usable-headroom-launcher-found-tried-path-loc","errorCode":null,"errorMessage":"No usable Headroom launcher found. Tried PATH, local npm, global npm, and Python. Install headroom-ai (npm or pip) and ensure one launcher is available.\\n${errors.length > 0 ? `Launch errors: ${errors.join(\"; \")}` : \"\"}","messagePattern":"No usable Headroom launcher found\\. Tried PATH, local npm, global npm, and Python\\. Install headroom-ai \\(npm or pip\\) and ensure one launcher is available\\.\\\\n(.+?)` : \"\"\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/openclaw/src/proxy-manager.ts","lineNumber":207,"sourceCode":"        this.logger.debug(`Launcher unavailable: ${spec.label}`);\n        continue;\n      }\n\n      try {\n        const child = spawn(spec.command, spec.args, {\n          detached: true,\n          shell: spec.useShell === true,\n          stdio: \"ignore\",\n        });\n        child.unref();\n        this.logger.info(`Auto-start launcher selected: ${spec.label}`);\n        return;\n      } catch (error) {\n        errors.push(`${spec.label}: ${String(error)}`);\n      }\n    }\n\n    throw new Error(\n      \"No usable Headroom launcher found. Tried PATH, local npm, global npm, and Python. \" +\n        \"Install headroom-ai (npm or pip) and ensure one launcher is available.\\n\" +\n        (errors.length > 0 ? `Launch errors: ${errors.join(\"; \")}` : \"\"),\n    );\n  }\n\n  private buildLaunchSpecs(host: string, port: string): LaunchSpec[] {\n    const commonArgs = [\"proxy\", \"--host\", host, \"--port\", port];\n    const retryMaxAttempts = this.config.retryMaxAttempts;\n    if (Number.isInteger(retryMaxAttempts)) {\n      commonArgs.push(\"--retry-max-attempts\", String(retryMaxAttempts));\n    }\n\n    const connectTimeoutSeconds = this.config.connectTimeoutSeconds;\n    if (Number.isInteger(connectTimeoutSeconds)) {\n      commonArgs.push(\"--connect-timeout-seconds\", String(connectTimeoutSeconds));\n    }\n","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/plugins/openclaw/src/proxy-manager.ts#L189-L225","documentation":"Auto-start tried every launcher strategy — the 'headroom' binary on PATH, a local npm install, a global npm install, and a Python entry point — and every spawn threw. The collected per-launcher errors are appended to the message, which is the key diagnostic: it shows exactly why each candidate failed. This means headroom-ai is not installed (or not callable) in the runtime environment of the spawned process.","triggerScenarios":"autoStart true and startHeadroomProxy runs; all launch specs fail, e.g. no 'headroom' on PATH, no node_modules/headroom-ai locally or globally, no Python headroom module, or spawn permissions/shell issues captured in the errors array.","commonSituations":"headroom-ai installed in a different environment than the one spawning (nvm switch, venv mismatch, Docker layer missing the CLI); CI image without headroom-ai; npm global bin dir not on PATH for the spawning process; Windows shell resolution differences.","solutions":["Read the Launch errors list in the message — it tells you which launchers were attempted and why each failed","Install headroom-ai where the spawning process can see it: npm install -g headroom-ai (then confirm 'headroom' is on PATH) or pip install headroom-ai","If installed but not found, fix PATH for the spawning process (e.g. add the npm global bin directory) and restart it","Alternatively pre-start the proxy yourself and disable autoStart so no launcher is needed"],"exampleFix":"# before: headroom-ai absent from the runtime\nmanager.configure({ autoStart: true }); // throws at launch\n\n# after: install it, or run it yourself\nnpm install -g headroom-ai && export PATH=\"$(npm bin -g):$PATH\"\n# or: headroom proxy --port 8787 &  + manager.configure({ proxyUrl: ... })","handlingStrategy":"validation","validationCode":"import { spawnSync } from \"node:child_process\";\n\nfunction headroomLauncherAvailable(): boolean {\n  return spawnSync(\"headroom\", [\"--version\"], { encoding: \"utf8\" }).status === 0;\n}\n\nif (config.autoStart === true && !headroomLauncherAvailable()) {\n  throw new Error(\"autoStart enabled but no headroom launcher on PATH — install headroom-ai first\");\n}","typeGuard":"function hasLauncherOnPath(label: string): boolean {\n  // cheap presence check for the exact launchers the manager tries\n  return spawnSync(\"which\", [label]).status === 0;\n}","tryCatchPattern":"try {\n  await manager.resolveProxyUrl();\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"No usable Headroom launcher found\")) {\n    throw new Error(\"Install headroom-ai (npm i -g headroom-ai or pip install headroom-ai) and ensure it is on PATH\");\n  }\n  throw e;\n}","preventionTips":["Install headroom-ai as a provisioning step in Dockerfiles/CI images and assert 'headroom --version' passes","Verify the spawning process's PATH actually contains the npm global bin dir before enabling autoStart","Prefer pre-starting the proxy and disabling autoStart in locked-down environments where spawning is unreliable"],"tags":["proxy","installation","auto-start","environment","openclaw"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}