{"record":{"id":"b64e99e8cc10dd70","repo":"sveltejs/kit","slug":"env-prefix-xff-depth-must-be-a-positive-int","errorCode":null,"errorMessage":"${env_prefix + 'XFF_DEPTH'} must be a positive integer","messagePattern":"(.+?) must be a positive integer","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/adapter-node/src/handler.js","lineNumber":164,"sourceCode":"\tconst response = await server.respond(request, {\n\t\tplatform: { req },\n\t\tgetClientAddress: () => {\n\t\t\tif (address_header) {\n\t\t\t\tif (!(address_header in req.headers)) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Address header was specified with ${\n\t\t\t\t\t\t\tenv_prefix + 'ADDRESS_HEADER'\n\t\t\t\t\t\t}=${address_header} but is absent from request`\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tconst value = /** @type {string} */ (req.headers[address_header]) || '';\n\n\t\t\t\tif (address_header === 'x-forwarded-for') {\n\t\t\t\t\tconst addresses = value.split(',');\n\n\t\t\t\t\tif (xff_depth < 1) {\n\t\t\t\t\t\tthrow new Error(`${env_prefix + 'XFF_DEPTH'} must be a positive integer`);\n\t\t\t\t\t}\n\n\t\t\t\t\tif (xff_depth > addresses.length) {\n\t\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\t`${env_prefix + 'XFF_DEPTH'} is ${xff_depth}, but only found ${\n\t\t\t\t\t\t\t\taddresses.length\n\t\t\t\t\t\t\t} addresses`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn addresses[addresses.length - xff_depth].trim();\n\t\t\t\t}\n\n\t\t\t\treturn value;\n\t\t\t}\n\n\t\t\treturn (\n\t\t\t\treq.connection?.remoteAddress ||\n\t\t\t\t// @ts-expect-error","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/sveltejs/kit/blob/03f1687fe612ce3d2d9131139b5b188d9cf90c64/packages/adapter-node/src/handler.js#L146-L182","documentation":"XFF_DEPTH selects which entry in a comma-separated x-forwarded-for list is treated as the client address (counting from the right). The value must be a positive integer; a value below 1 is meaningless and is rejected when the x-forwarded-for header is inspected.","triggerScenarios":"XFF_DEPTH env var is set to 0, negative, or a non-numeric value and a request arrives with an x-forwarded-for header, triggering getClientAddress.","commonSituations":"Typos like XFF_DEPTH=0, exporting an empty string, or misreading the semantics (1 = closest proxy, not 0).","solutions":["Set XFF_DEPTH to a positive integer, e.g. 1","Unset XFF_DEPTH to use the default of 1","Verify the deployment platform isn't injecting an invalid default value"],"exampleFix":"// before\nXFF_DEPTH=0\n// after\nXFF_DEPTH=1","handlingStrategy":"validation","validationCode":"const depth = Number(process.env.XFF_DEPTH ?? 1);\nif (!Number.isInteger(depth) || depth < 1) {\n  throw new Error('XFF_DEPTH must be a positive integer');\n}","typeGuard":"function isValidXffDepth(v) {\n  const n = Number(v);\n  return Number.isInteger(n) && n >= 1;\n}","tryCatchPattern":"try {\n  await start();\n} catch (err) {\n  if (String(err.message).includes('must be a positive integer')) {\n    console.error('Set XFF_DEPTH to a positive integer (default 1)');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Default to XFF_DEPTH=1 and only increase for known proxy chains","Remember 1 = closest to the server, not 0","Validate env vars in CI before deploy"],"tags":["http","headers","proxy","configuration"],"backgroundTag":"invalid-xff-depth","analyzedSha":"03f1687fe612ce3d2d9131139b5b188d9cf90c64","analyzedAt":"2026-09-02T02:01:50.504Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}