withastro/astro · error · AstroError

ClientAddressNotAvailable

ClientAddressNotAvailable

Error message

`Astro.clientAddress` is not available in the `${adapterName}` adapter. File an issue with the adapter to add support.

What it means

Thrown when Astro.clientAddress is read on a server-rendered route but the active adapter does not provide a clientAddress value. The adapter is responsible for populating pipeline.clientAddress; if it has an adapterName but no address, the IP cannot be trusted and Astro refuses to return a fabricated one.

Source

Thrown at packages/astro/src/core/fetch/fetch-state.ts:603

	}

	getClientAddress(): string {
		const { pipeline, clientAddress } = this;
		const routeData = this.routeData!;

		if (routeData.prerender) {
			throw new AstroError({
				...AstroErrorData.PrerenderClientAddressNotAvailable,
				message: AstroErrorData.PrerenderClientAddressNotAvailable.message(routeData.component),
			});
		}

		if (clientAddress) {
			return clientAddress;
		}

		if (pipeline.adapterName) {
			throw new AstroError({
				...AstroErrorData.ClientAddressNotAvailable,
				message: AstroErrorData.ClientAddressNotAvailable.message(pipeline.adapterName),
			});
		}

		throw new AstroError(AstroErrorData.StaticClientAddressNotAvailable);
	}

	getCookies(): AstroCookies {
		return this.cookies;
	}

	getCsp(): APIContext['csp'] {
		const state = this;
		const { pipeline } = this;
		if (!pipeline.manifest.csp) {
			if (pipeline.runtimeMode === 'production') {
				pipeline.logger.warn(

View on GitHub (pinned to d081033d5f)

Solutions

1. Upgrade your adapter to a version that implements clientAddress forwarding.
2. Use an adapter that documents clientAddress support, or file an issue with the adapter maintainer as the message suggests.
3. Read the forwarded IP from request headers (e.g. Astro.request.headers.get('x-forwarded-for')) when you control the proxy, after validating the header.

Example fix

// before
const ip = Astro.clientAddress; // throws on unsupported adapter

// after
const ip =
  Astro.request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? 'unknown';

// Check adapter support before reading clientAddress.
const adapterName = (Astro as any).pipeline?.adapterName;
const supportsClientAddress = ['@astrojs/node', '@astrojs/vercel', '@astrojs/cloudflare']
  .some((a) => adapterName?.startsWith(a));
const ip = supportsClientAddress ? Astro.clientAddress : undefined;

function adapterSupportsClientAddress(pipeline: { adapterName?: string }): boolean {
  return Boolean(pipeline.adapterName); // refine per known adapters
}

try {
  ip = Astro.clientAddress;
} catch (e) {
  if (e instanceof Error && /not available/i.test(e.message)) {
    ip = Astro.request.headers.get('x-forwarded-for') ?? undefined;
  } else throw e;
}

When it happens

Trigger: Deploying to an adapter that has not implemented client address forwarding (pipeline.adapterName is set but clientAddress is undefined) and then reading Astro.clientAddress. Common with bare or older community adapters, or when sitting behind a proxy the adapter does not read.

Common situations: Using the Node adapter in standalone mode behind a reverse proxy without configuring trusted proxy headers; using an adapter version that predates clientAddress support; switching adapters from one that supports clientAddress (e.g. a platform adapter) to one that does not.

Related errors

• StaticClientAddressNotAvailable
• Integration "${maybeConflictingIntegration}" conflicts with
• AdapterSupportOutputMismatch
• PrerenderClientAddressNotAvailable
• StaticClientAddressNotAvailable

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/a33e8d7dee9c1454. Report an issue: GitHub.