sveltejs/kit · error · Error

${env_prefix + 'XFF_DEPTH'} must be a positive integer

Error message

${env_prefix + 'XFF_DEPTH'} must be a positive integer

What it means

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.

Source

Thrown at packages/adapter-node/src/handler.js:164

	const response = await server.respond(request, {
		platform: { req },
		getClientAddress: () => {
			if (address_header) {
				if (!(address_header in req.headers)) {
					throw new Error(
						`Address header was specified with ${
							env_prefix + 'ADDRESS_HEADER'
						}=${address_header} but is absent from request`
					);
				}

				const value = /** @type {string} */ (req.headers[address_header]) || '';

				if (address_header === 'x-forwarded-for') {
					const addresses = value.split(',');

					if (xff_depth < 1) {
						throw new Error(`${env_prefix + 'XFF_DEPTH'} must be a positive integer`);
					}

					if (xff_depth > addresses.length) {
						throw new Error(
							`${env_prefix + 'XFF_DEPTH'} is ${xff_depth}, but only found ${
								addresses.length
							} addresses`
						);
					}
					return addresses[addresses.length - xff_depth].trim();
				}

				return value;
			}

			return (
				req.connection?.remoteAddress ||
				// @ts-expect-error

View on GitHub (pinned to 03f1687fe6)

Solutions

1. Set XFF_DEPTH to a positive integer, e.g. 1
2. Unset XFF_DEPTH to use the default of 1
3. Verify the deployment platform isn't injecting an invalid default value

Example fix

// before
XFF_DEPTH=0
// after
XFF_DEPTH=1

const depth = Number(process.env.XFF_DEPTH ?? 1);
if (!Number.isInteger(depth) || depth < 1) {
  throw new Error('XFF_DEPTH must be a positive integer');
}

function isValidXffDepth(v) {
  const n = Number(v);
  return Number.isInteger(n) && n >= 1;
}

try {
  await start();
} catch (err) {
  if (String(err.message).includes('must be a positive integer')) {
    console.error('Set XFF_DEPTH to a positive integer (default 1)');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: Typos like XFF_DEPTH=0, exporting an empty string, or misreading the semantics (1 = closest proxy, not 0).

Related errors

• Could not determine host. The request must have a value prov
• Address header was specified with ${env_prefix + 'ADDRESS_HE
• ${env_prefix + 'XFF_DEPTH'} is ${xff_depth}, but only found
• The ${port_header} header specified ${port} which is an inva
• Multiple values provided for ${name} header where only one e

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/b64e99e8cc10dd70. Report an issue: GitHub.