headroomlabs-ai/headroom · error · Error

Headroom proxy not detected on default endpoints (${defaultC

Error message

Headroom proxy not detected on default endpoints (${defaultCandidates.join(", ")}). Set proxyUrl explicitly or enable autoStart.

What it means

This is the no-configuration failure path: no explicit proxyUrl was given, neither default local endpoint (http://127.0.0.1:<port> nor http://localhost:<port>, default port 8787) had a Headroom proxy, and autoStart is not enabled so the manager cannot create one. The message names the exact endpoints probed and the two supported remedies.

Source

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

        this.config.startupTimeoutMs ?? 20_000,
      );
      if (startedProbe.reachable && startedProbe.isHeadroom) {
        this.proxyUrl = startupUrl;
        this.logger.info(`Headroom proxy started and reachable at ${startupUrl}`);
        return startupUrl;
      }
      throw new Error(
        `Attempted to start Headroom proxy, but it was not reachable at ${startupUrl} (${startedProbe.reason ?? "unknown"}).`,
      );
    }

    if (explicitUrl) {
      throw new Error(
        `Headroom proxy not reachable at ${explicitUrl}. Ensure the proxy is running first.`,
      );
    }

    throw new Error(
      `Headroom proxy not detected on default endpoints (${defaultCandidates.join(", ")}). ` +
        "Set proxyUrl explicitly or enable autoStart.",
    );
  }

  private getProxyPort(): number {
    const rawPort = this.config.proxyPort;
    if (!Number.isInteger(rawPort) || rawPort === undefined) return 8787;
    if (rawPort < 1 || rawPort > 65535) {
      throw new Error("proxyPort must be an integer between 1 and 65535");
    }
    return rawPort;
  }

  private getDefaultProxyCandidates(port: number): string[] {
    return [`http://127.0.0.1:${port}`, `http://localhost:${port}`];
  }

View on GitHub (pinned to 322425c43b)

Solutions

Set proxyUrl in the manager config to wherever Headroom actually listens (including remote hosts)
Or enable autoStart so the manager launches Headroom locally on demand
Or start Headroom manually on the default port: headroom proxy --port 8787

Example fix

// before: defaults, nothing running
await manager.resolveProxyUrl(); // throws

// after: any one of these
manager.configure({ proxyUrl: "http://127.0.0.1:8787" }); // connect to existing
manager.configure({ autoStart: true }); // let it spawn
// or shell: headroom proxy --port 8787 &

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast at config time instead of during proxy resolution
function validateProxyConfig(cfg: { proxyUrl?: string; autoStart?: boolean }): void {
  if (!cfg.proxyUrl && cfg.autoStart !== true) {
    throw new Error(
      "Headroom proxy requires proxyUrl or autoStart; neither is set — nothing can be connected to or started"
    );
  }
}

Type guard

type ProxyConfig = { proxyUrl?: string; autoStart?: boolean };

function isResolvableConfig(cfg: ProxyConfig): cfg is ProxyConfig & { proxyUrl: string } | ProxyConfig & { autoStart: true } {
  return typeof cfg.proxyUrl === "string" || cfg.autoStart === true;
}

Try / catch

try {
  await manager.resolveProxyUrl();
} catch (e) {
  if (e instanceof Error && e.message.includes("not detected on default endpoints")) {
    throw new Error("No proxy configured or running — set proxyUrl or enable autoStart in settings");
  }
  throw e;
}

Prevention

Make proxyUrl or autoStart a required field in the client's config schema so misconfig fails at load time
Document the default endpoints (127.0.0.1:8787, localhost:8787) so users know what gets probed
In shared environments, always set an explicit proxyUrl — never rely on default discovery

When it happens

Trigger: Constructing/resolving the proxy manager with default config (no proxyUrl, autoStart false/undefined) on a machine where no Headroom proxy is running — the manager probes 127.0.0.1:8787 and localhost:8787, finds nothing Headroom-like, and throws.

Common situations: Fresh install / first run without any proxy setup; proxy started with a non-default port so the default candidates miss it; proxy running on a remote host but the client was never told; local proxy crashed earlier and the client restarted.

Related errors

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