withastro/astro · error · AstroError

StaticClientAddressNotAvailable

StaticClientAddressNotAvailable

Error message

`Astro.clientAddress` is only available on pages that are server-rendered.

What it means

Thrown by getClientAddress() as the final fallback when the route is server-rendered, no adapter is configured, and clientAddress was never set. With no adapter and no stored address there is no source for the visitor IP at all, so reading Astro.clientAddress on a purely static/local setup is impossible.

Source

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

		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(
					'csp',
					`context.csp was used when rendering the route ${colors.green(state.routeData!.route)}, but CSP was not configured. For more information, see https://docs.astro.build/en/reference/configuration-reference/#securitycsp`,
				);
			}
			return undefined;
		}

View on GitHub (pinned to d081033d5f)

Solutions

Install and configure an adapter that provides clientAddress before reading it.
Avoid Astro.clientAddress in code paths exercised during local dev without an adapter.
Fall back to request headers in dev/test environments where no adapter is present.

Example fix

// before
const ip = Astro.clientAddress; // throws, no adapter configured

// after
// install: npx astro add node
const ip = Astro.clientAddress;

Defensive patterns

Strategy: validation

Validate before calling

// Avoid clientAddress entirely when no adapter is configured.
const hasAdapter = Boolean((Astro as any).pipeline?.adapterName);
const ip = hasAdapter ? Astro.clientAddress : undefined;

Type guard

function hasAdapter(pipeline: { adapterName?: string }): boolean {
  return Boolean(pipeline.adapterName);
}

Try / catch

try {
  ip = Astro.clientAddress;
} catch (e) {
  if (e instanceof Error && /server-rendered/i.test(e.message)) {
    ip = undefined;
  } else throw e;
}

Prevention

Install an adapter before relying on clientAddress.
Skip clientAddress-dependent code in dev/test without an adapter.
Use feature flags gated on adapter presence.

When it happens

Trigger: Running a server-rendered route via the dev server or a static build with no adapter, and accessing Astro.clientAddress. The throw fires after the adapterName check because pipeline.adapterName is falsy.

Common situations: Reading Astro.clientAddress during `astro dev` on a route that is on-demand but the project has no adapter installed yet; testing clientAddress logic locally before deploying; a project that is output 'static' but a single route is forced server-rendered.

Related errors

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