What causes "proxyPort must be an integer between 1 and 65535" in headroomlabs-ai/headroom?

Set proxyPort to an integer between 1 and 65535 (e.g. 8787)

headroomlabs-ai/headroom · error · Error

proxyPort must be an integer between 1 and 65535

Error message

proxyPort must be an integer between 1 and 65535

What it means

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.

Source

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

    }

    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}`];
  }

  /**
   * Stop manager state. Spawned proxy processes are detached and externally managed.
   */
  async stop(): Promise<void> {
    this.proxyUrl = null;
  }

  getUrl(): string | null {
    return this.proxyUrl;
  }

View on GitHub (pinned to 322425c43b)

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

Example fix

// before
manager.configure({ proxyPort: 0 }); // throws

// after
manager.configure({ proxyPort: 8787 });
// or omit proxyPort for the default

Defensive patterns

Strategy: validation

Validate before calling

function validProxyPort(port: unknown): port is number {
  return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65535;
}

if (config.proxyPort !== undefined && !validProxyPort(config.proxyPort)) {
  throw new Error(`proxyPort must be an integer 1-65535, got ${config.proxyPort}`);
}

Type guard

function isValidProxyPort(port: unknown): port is number {
  return typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65535;
}

Prevention

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

When it happens

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

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

Related errors

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