paperclipai/paperclip · error · Error

BROKER_PROTECTED_PORTS contains a non-numeric entry: ${JSON.

Error message

BROKER_PROTECTED_PORTS contains a non-numeric entry: ${JSON.stringify(token)}

What it means

parseProtectedPorts guard in loadHostConfig startup: a token in the comma/space-separated BROKER_PROTECTED_PORTS list doesn't match the digits-only pattern. Fails closed — the broker refuses to start rather than silently protecting nothing after skipping the bad entry.

Source

Thrown at packages/tailscale-https-broker/src/port-policy.ts:36

}

/**
 * Parse `BROKER_PROTECTED_PORTS` (comma/space separated) into a sorted, deduped
 * set of operator-protected ports (PAP-17285).
 *
 * Fails closed: a malformed list throws so the broker refuses to start rather
 * than silently protecting nothing. Protecting a port the broker cannot mutate
 * anyway is harmless, so no range restriction is applied — but `443` is rejected
 * because the primary route has its own stronger, non-optional invariant and
 * listing it here would imply it were opt-in.
 */
export function parseProtectedPorts(raw: string | undefined): number[] {
  if (raw === undefined) return [];
  const tokens = raw.split(/[,\s]+/).filter((token) => token.length > 0);
  const ports = new Set<number>();
  for (const token of tokens) {
    if (!/^[0-9]{1,5}$/.test(token)) {
      throw new Error(`BROKER_PROTECTED_PORTS contains a non-numeric entry: ${JSON.stringify(token)}`);
    }
    const port = Number(token);
    if (port < 1 || port > 65535) {
      throw new Error(`BROKER_PROTECTED_PORTS contains an out-of-range port: ${token}`);
    }
    if (port === 443) {
      throw new Error("BROKER_PROTECTED_PORTS must not list 443; the primary route is always protected");
    }
    ports.add(port);
  }
  return [...ports].sort((a, b) => a - b);
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Remove or correct the non-numeric entry in BROKER_PROTECTED_PORTS; use a comma-separated list of port numbers.

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/port-policy.ts:36 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/c9c4e79b5fd1d40c. Report an issue: GitHub.