paperclipai/paperclip · error · Error

TRUST_PROXY: invalid integer value ${JSON.stringify(raw)} —

Error message

TRUST_PROXY: invalid integer value ${JSON.stringify(raw)} — use a positive integer with no leading zeros or whitespace

What it means

parseTrustProxyEnv guard: the TRUST_PROXY value is purely digits-and-whitespace (e.g. "01" or " 2") but did not match the strict positive-integer pattern. Such values are treated as typo'd hop counts, not subnet lists, and rejected with guidance instead of being misinterpreted.

Source

Thrown at server/src/middleware/trust-proxy.ts:88

 * Throws `Error` with an explanatory message if the value is malformed.
 */
export function parseTrustProxyEnv(raw: string | undefined): TrustProxyValue | undefined {
  if (raw === undefined) return undefined;
  // We intentionally trim only the *outer* value — tokens inside the
  // comma list are trimmed individually below. Leading/trailing whitespace
  // around the whole value (e.g. " 2 ") is accepted because trim() reduces
  // it to "2" before STRICT_POS_INT_RE is applied; only *internal*
  // whitespace (e.g. "1 2") falls through to the subnet path and errors as
  // an unrecognised token.
  const value = raw.trim();
  if (value === "" || value === "false" || value === "0") return undefined;
  if (value === "true") return true;
  if (STRICT_POS_INT_RE.test(value)) return Number(value);
  // Reject the "01" / " 2" forms explicitly — if the value is *purely*
  // digits-or-whitespace but didn't match STRICT_POS_INT_RE, it's a
  // typo, not a subnet list.
  if (/^\s*\d+\s*$/.test(raw)) {
    throw new Error(
      `TRUST_PROXY: invalid integer value ${JSON.stringify(raw)} — use a positive integer with no leading zeros or whitespace`,
    );
  }
  const tokens = value
    .split(",")
    .map((t) => t.trim())
    .filter((t) => t.length > 0);
  if (tokens.length === 0) return undefined;
  for (const token of tokens) {
    if (!isValidSubnetToken(token)) {
      throw new Error(
        `TRUST_PROXY: unrecognized token ${JSON.stringify(token)} — expected one of {loopback, linklocal, uniquelocal} or a CIDR like 10.0.0.0/8 or fd00::/8`,
      );
    }
  }
  return tokens;
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Set TRUST_PROXY to a positive integer with no leading zeros or whitespace, e.g. TRUST_PROXY=1.

When it happens

Trigger: Thrown at server/src/middleware/trust-proxy.ts:88 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/fee83faca0595439. Report an issue: GitHub.