paperclipai/paperclip · error · Error

port out of range [${MIN_PORT}, ${MAX_PORT}]

Error message

port out of range [${MIN_PORT}, ${MAX_PORT}]

What it means

assertCanonicalPort guard: the value is an integer but falls outside the valid TCP range [1, 65535] (negative, zero, NaN/Infinity, or too large). The port cannot name a real TCP listener, so it is rejected at the boundary.

Source

Thrown at packages/tailscale-https-broker/src/integers.ts:24

/** Ports are constrained to the valid TCP range. */
export const MIN_PORT = 1;
export const MAX_PORT = 65535;

/**
 * Assert a JSON-decoded value is a canonical, safe, in-range port number.
 * Rejects non-numbers, non-integers, NaN/Infinity, negatives, and out-of-range
 * values. Returns the number so call sites read as validated.
 */
export function assertCanonicalPort(value: unknown): number {
  if (typeof value !== "number") {
    throw new Error("port must be a JSON number");
  }
  if (!Number.isInteger(value)) {
    throw new Error("port must be an integer");
  }
  if (value < MIN_PORT || value > MAX_PORT) {
    throw new Error(`port out of range [${MIN_PORT}, ${MAX_PORT}]`);
  }
  return value;
}

/**
 * Parse an integer from an untrusted STRING with strict canonical rules.
 * Rejects: empty, whitespace, signs, leading zeros (non-canonical), decimals,
 * exponents, thousands separators, Unicode digits, and anything that does not
 * round-trip exactly back to its canonical decimal form. Used at any boundary
 * where a numeric value could arrive as text.
 */
export function parseCanonicalIntegerString(raw: unknown): number {
  if (typeof raw !== "string") {
    throw new Error("expected a string integer");
  }
  // Only ASCII digits, at least one, no sign, no whitespace. `^[0-9]+$` with a
  // JS regex still matches only ASCII 0-9 (it does not match Unicode digits
  // unless the `u` + property-escape form is used), which is what we want.

View on GitHub (pinned to 120ae5428f)

Solutions

1. Choose a port within the allowed range shown in the message [MIN_PORT, MAX_PORT].

When it happens

Trigger: Thrown at packages/tailscale-https-broker/src/integers.ts:24 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/f4fa80fb15b6db82. Report an issue: GitHub.