paperclipai/paperclip · error · Error

port must be a JSON number

Error message

port must be a JSON number

What it means

assertCanonicalPort guard: the JSON-decoded port value is not a JS number at all (string, null, object, etc.). Ports are never derived from raw strings or unvalidated JSON, so the value is rejected before any command or Serve mutation is generated from it.

Source

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

/**
 * Canonical integer parsing for the broker. Commands and Serve mutations are
 * generated only from integers that pass these checks, never from raw strings,
 * URLs, or unvalidated JSON (PAP-17050 verdict requirement #4).
 */

/** 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 {

View on GitHub (pinned to 120ae5428f)

Solutions

1. Provide the port as a JSON number, not a string or other type.

When it happens

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