{"record":{"id":"00b92e888136741f","repo":"headroomlabs-ai/headroom","slug":"headroom-proxy-not-detected-on-default-endpoints","errorCode":null,"errorMessage":"Headroom proxy not detected on default endpoints (${defaultCandidates.join(\", \")}). Set proxyUrl explicitly or enable autoStart.","messagePattern":"Headroom proxy not detected on default endpoints \\((.+?)\\)\\. Set proxyUrl explicitly or enable autoStart\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/openclaw/src/proxy-manager.ts","lineNumber":148,"sourceCode":"        this.config.startupTimeoutMs ?? 20_000,\n      );\n      if (startedProbe.reachable && startedProbe.isHeadroom) {\n        this.proxyUrl = startupUrl;\n        this.logger.info(`Headroom proxy started and reachable at ${startupUrl}`);\n        return startupUrl;\n      }\n      throw new Error(\n        `Attempted to start Headroom proxy, but it was not reachable at ${startupUrl} (${startedProbe.reason ?? \"unknown\"}).`,\n      );\n    }\n\n    if (explicitUrl) {\n      throw new Error(\n        `Headroom proxy not reachable at ${explicitUrl}. Ensure the proxy is running first.`,\n      );\n    }\n\n    throw new Error(\n      `Headroom proxy not detected on default endpoints (${defaultCandidates.join(\", \")}). ` +\n        \"Set proxyUrl explicitly or enable autoStart.\",\n    );\n  }\n\n  private getProxyPort(): number {\n    const rawPort = this.config.proxyPort;\n    if (!Number.isInteger(rawPort) || rawPort === undefined) return 8787;\n    if (rawPort < 1 || rawPort > 65535) {\n      throw new Error(\"proxyPort must be an integer between 1 and 65535\");\n    }\n    return rawPort;\n  }\n\n  private getDefaultProxyCandidates(port: number): string[] {\n    return [`http://127.0.0.1:${port}`, `http://localhost:${port}`];\n  }\n","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/plugins/openclaw/src/proxy-manager.ts#L130-L166","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: defaults, nothing running\nawait manager.resolveProxyUrl(); // throws\n\n// after: any one of these\nmanager.configure({ proxyUrl: \"http://127.0.0.1:8787\" }); // connect to existing\nmanager.configure({ autoStart: true }); // let it spawn\n// or shell: headroom proxy --port 8787 &","handlingStrategy":"validation","validationCode":"// Fail fast at config time instead of during proxy resolution\nfunction validateProxyConfig(cfg: { proxyUrl?: string; autoStart?: boolean }): void {\n  if (!cfg.proxyUrl && cfg.autoStart !== true) {\n    throw new Error(\n      \"Headroom proxy requires proxyUrl or autoStart; neither is set — nothing can be connected to or started\"\n    );\n  }\n}","typeGuard":"type ProxyConfig = { proxyUrl?: string; autoStart?: boolean };\n\nfunction isResolvableConfig(cfg: ProxyConfig): cfg is ProxyConfig & { proxyUrl: string } | ProxyConfig & { autoStart: true } {\n  return typeof cfg.proxyUrl === \"string\" || cfg.autoStart === true;\n}","tryCatchPattern":"try {\n  await manager.resolveProxyUrl();\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"not detected on default endpoints\")) {\n    throw new Error(\"No proxy configured or running — set proxyUrl or enable autoStart in settings\");\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["proxy","configuration","setup","openclaw"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}