paperclipai/paperclip · error · Error

TRUST_PROXY: unrecognized token ${JSON.stringify(token)} — e

Error message

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

What it means

parseTrustProxyEnv token guard: while splitting the comma list, a token was neither a named preset (loopback/linklocal/uniquelocal) nor a parseable CIDR. The message lists the accepted forms so the operator can correct the TRUST_PROXY entry.

Source

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

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

/**
 * Apply the parsed value to the given Express app. No-op when the value
 * is `undefined`, preserving Express's default (trust nothing).
 */
export function applyTrustProxy(
  app: { set: (key: string, value: TrustProxyValue) => unknown },
  value: TrustProxyValue | undefined,
): void {
  if (value === undefined) return;
  app.set("trust proxy", value);
}

View on GitHub (pinned to 120ae5428f)

Solutions

1. Use one of {loopback, linklocal, uniquelocal} or a valid CIDR such as 10.0.0.0/8 or fd00::/8 in TRUST_PROXY.

When it happens

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