headroomlabs-ai/headroom · error · Error

No usable Headroom launcher found. Tried PATH, local npm, gl

Error message

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("; ")}` : ""}

What it means

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.

Source

Thrown at plugins/openclaw/src/proxy-manager.ts:207

        this.logger.debug(`Launcher unavailable: ${spec.label}`);
        continue;
      }

      try {
        const child = spawn(spec.command, spec.args, {
          detached: true,
          shell: spec.useShell === true,
          stdio: "ignore",
        });
        child.unref();
        this.logger.info(`Auto-start launcher selected: ${spec.label}`);
        return;
      } catch (error) {
        errors.push(`${spec.label}: ${String(error)}`);
      }
    }

    throw new Error(
      "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("; ")}` : ""),
    );
  }

  private buildLaunchSpecs(host: string, port: string): LaunchSpec[] {
    const commonArgs = ["proxy", "--host", host, "--port", port];
    const retryMaxAttempts = this.config.retryMaxAttempts;
    if (Number.isInteger(retryMaxAttempts)) {
      commonArgs.push("--retry-max-attempts", String(retryMaxAttempts));
    }

    const connectTimeoutSeconds = this.config.connectTimeoutSeconds;
    if (Number.isInteger(connectTimeoutSeconds)) {
      commonArgs.push("--connect-timeout-seconds", String(connectTimeoutSeconds));
    }

View on GitHub (pinned to 322425c43b)

Solutions

1. Read the Launch errors list in the message — it tells you which launchers were attempted and why each failed
2. 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
3. If installed but not found, fix PATH for the spawning process (e.g. add the npm global bin directory) and restart it
4. Alternatively pre-start the proxy yourself and disable autoStart so no launcher is needed

Example fix

# before: headroom-ai absent from the runtime
manager.configure({ autoStart: true }); // throws at launch

# after: install it, or run it yourself
npm install -g headroom-ai && export PATH="$(npm bin -g):$PATH"
# or: headroom proxy --port 8787 &  + manager.configure({ proxyUrl: ... })

import { spawnSync } from "node:child_process";

function headroomLauncherAvailable(): boolean {
  return spawnSync("headroom", ["--version"], { encoding: "utf8" }).status === 0;
}

if (config.autoStart === true && !headroomLauncherAvailable()) {
  throw new Error("autoStart enabled but no headroom launcher on PATH — install headroom-ai first");
}

function hasLauncherOnPath(label: string): boolean {
  // cheap presence check for the exact launchers the manager tries
  return spawnSync("which", [label]).status === 0;
}

try {
  await manager.resolveProxyUrl();
} catch (e) {
  if (e instanceof Error && e.message.includes("No usable Headroom launcher found")) {
    throw new Error("Install headroom-ai (npm i -g headroom-ai or pip install headroom-ai) and ensure it is on PATH");
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot auto-start Headroom at ${startupUrl}: port is in use
• Attempted to start Headroom proxy, but it was not reachable
• Headroom OpenCode transport shim loaded without HEADROOM_OPE
• Invalid {TOOL_INJECTION_STICKY_ENV}={normalized!r}; expected
• Headroom proxy startup is disabled

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/7b27dfb610b38b82. Report an issue: GitHub.