sveltejs/kit · error · Error

Address header was specified with ${env_prefix}ADDRESS_HEADE

Error message

Address header was specified with ${env_prefix}ADDRESS_HEADER=${address_header} but is absent from request

What it means

When ADDRESS_HEADER is set, get_client_address first tries Bun's requestIP(); if that returns null (e.g. unix sockets), it falls back to reading the configured header. If that header is missing from the request the adapter throws rather than silently returning undefined. This means the deployment is configured to trust a header that the proxy did not send.

Source

Thrown at packages/adapter-bun/src/handler.js:110

	// canonicalized so the caller's comparison with url.origin matches (case, default ports)
	return new URL(`${protocol}://${host}${port ? `:${port}` : ''}`).origin;
}

/**
 * @param {Request} request
 * @param {BunServer<undefined>} bun_server
 * @returns {string}
 */
function get_client_address(request, bun_server) {
	if (!address_header) {
		// requestIP() is null over unix sockets; undefined matches adapter-node
		return /** @type {string} */ (bun_server.requestIP(request)?.address);
	}

	const value = request.headers.get(address_header);
	if (value === null) {
		throw new Error(
			`Address header was specified with ${env_prefix}ADDRESS_HEADER=${address_header} but is absent from request`
		);
	}
	if (address_header !== 'x-forwarded-for') return value;

	const addresses = value.split(',');
	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();
}

View on GitHub (pinned to 03f1687fe6)

Solutions

Configure your proxy to always set the address header, e.g. nginx: `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`.
Verify the ADDRESS_HEADER value matches the exact header name your proxy sends (lowercase).
Unset ADDRESS_HEADER so the adapter uses Bun's requestIP() when you are not behind a proxy.

Example fix

// nginx before
proxy_set_header Host $host; // X-Forwarded-For never set
// after
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Defensive patterns

Strategy: try-catch

Validate before calling

if (process.env.ADDRESS_HEADER && !req.headers.has(process.env.ADDRESS_HEADER)) {
  console.warn(`${process.env.ADDRESS_HEADER} missing; client IP will fail`);
}

Try / catch

let ip;
try {
  ip = getClientAddress(event);
} catch (err) {
  if (/Address header .* absent/.test(err.message)) {
    ip = '127.0.0.1'; // or log and continue with a fallback
  } else throw err;
}

Prevention

Have the proxy always set the address header (e.g. X-Forwarded-For).
Only set ADDRESS_HEADER when you are actually behind a proxy.
Note unix sockets make requestIP() null — the header becomes mandatory.

When it happens

Trigger: env has ADDRESS_HEADER=x-forwarded-for (or a custom name) but the request lacks that header — direct connections that bypass the proxy, or a proxy that doesn't set the header; requestIP() null over unix sockets plus missing header.

Common situations: Running Bun on a unix socket behind a proxy that strips X-Forwarded-For; mis-typed header name in ADDRESS_HEADER; local testing against a deployment-configured adapter.

Related errors

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