{"record":{"id":"c42a8fc60417cc4d","repo":"headroomlabs-ai/headroom","slug":"proxyport-must-be-an-integer-between-1-and-65535","errorCode":null,"errorMessage":"proxyPort must be an integer between 1 and 65535","messagePattern":"proxyPort must be an integer between 1 and 65535","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/openclaw/src/proxy-manager.ts","lineNumber":158,"sourceCode":"    }\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\n  /**\n   * Stop manager state. Spawned proxy processes are detached and externally managed.\n   */\n  async stop(): Promise<void> {\n    this.proxyUrl = null;\n  }\n\n  getUrl(): string | null {\n    return this.proxyUrl;\n  }","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/plugins/openclaw/src/proxy-manager.ts#L140-L176","documentation":"getProxyPort() validates the configured proxyPort: non-integers and undefined fall back to the default 8787, but an integer outside 1-65535 (0, negative, or > 65535) throws this error. It is a hard config validation so the manager never tries to build URLs with an invalid port.","triggerScenarios":"Passing config.proxyPort as an integer value like 0, -1, or 70000. Note: fractional values (8787.5), NaN, or strings are NOT integers and silently fall back to 8787 — only out-of-range integers throw.","commonSituations":"proxyPort: 0 read as 'any port' from another tool's convention; port taken from an env var parsed into a huge number; copy-paste of a container-mapped or computed port that overflows the valid range.","solutions":["Set proxyPort to an integer between 1 and 65535 (e.g. 8787)","If the port comes from configuration/env, clamp or validate it before passing it to the manager","Omit proxyPort entirely to use the default 8787"],"exampleFix":"// before\nmanager.configure({ proxyPort: 0 }); // throws\n\n// after\nmanager.configure({ proxyPort: 8787 });\n// or omit proxyPort for the default","handlingStrategy":"validation","validationCode":"function validProxyPort(port: unknown): port is number {\n  return typeof port === \"number\" && Number.isInteger(port) && port >= 1 && port <= 65535;\n}\n\nif (config.proxyPort !== undefined && !validProxyPort(config.proxyPort)) {\n  throw new Error(`proxyPort must be an integer 1-65535, got ${config.proxyPort}`);\n}","typeGuard":"function isValidProxyPort(port: unknown): port is number {\n  return typeof port === \"number\" && Number.isInteger(port) && port >= 1 && port <= 65535;\n}","tryCatchPattern":null,"preventionTips":["Validate proxyPort at config-load time with the same 1-65535 integer rule the manager enforces","Remember the manager silently defaults non-integers (8787.5, NaN, strings) — be explicit with integers only","When deriving the port from env vars, parse and range-check before injecting it into config"],"tags":["proxy","configuration","validation","openclaw"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}