withastro/astro · error · AstroError

AdapterSupportOutputMismatch

AdapterSupportOutputMismatch

Error message

The `${adapterName}` adapter is configured to output a static website, but the project contains server-rendered pages. Please install and configure the appropriate server adapter for your final deployment.

What it means

`AdapterSupportOutputMismatch` is thrown when the resolved settings have `buildOutput: 'server'` (the project contains server-rendered pages / `output: 'server'`) but the adapter registering itself declares `adapterFeatures.buildOutput: 'static'`. At build time it throws with a hint recommending a server-capable adapter; at dev time the same condition only logs a warning.

Solutions

Install/upgrade to an adapter version that supports server output — the error's hint names the recommendation for your adapter.
Or stay static: set `output: 'static'` (default) and make sure all pages are prerendered, removing on-demand routes.
Re-run `astro build` after the change to confirm the mismatch is gone.

Example fix

// before — static-only adapter with server output
export default defineConfig({
  output: 'server',
  integrations: [myStaticAdapter()],
});

// after — option A: use a server-capable adapter
export default defineConfig({ output: 'server', integrations: [myServerAdapter()] });
// after — option B: stay static
export default defineConfig({ output: 'static', integrations: [myStaticAdapter()] });

Defensive patterns

Strategy: validation

Validate before calling

// Config-time assertion: adapter capabilities must match the output mode
import node from '@astrojs/node';
const adapter = node({ mode: 'standalone' });
const output = 'server'; // your intended mode
if (output === 'server' && adapter.adapterFeatures?.buildOutput === 'static') {
  throw new Error('Configured adapter cannot emit server output; pick a server-capable adapter.');
}
export default defineConfig({ output, adapter });

Prevention

Check the adapter's documentation for supported output modes before setting `output: 'server'`.
Run a full `astro build` in CI so mismatches fail the pipeline, not production.
Treat the dev-mode warning about server output seriously — it predicts the build failure.

When it happens

Trigger: Using a static-only adapter (or static-only major version) together with `output: 'server'` in config, or with any page using `export const prerender = false`, and running `astro build`.

Common situations: Enabling SSR on a project deployed with a static-only adapter build; upgrading Astro but keeping an old adapter major that predates server output support; following an SSR tutorial without swapping the adapter.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/766d5f2441fb9f17. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/dev/adapter-validation.ts:38

export function validateSetAdapter(
	logger: AstroLogger,
	settings: AstroSettings,
	adapter: AstroAdapter,
	maybeConflictingIntegration: string,
	command?: 'dev' | 'build' | string,
) {
	if (settings.adapter && settings.adapter.name !== adapter.name) {
		throw new Error(
			`Integration "${maybeConflictingIntegration}" conflicts with "${settings.adapter.name}". You can only configure one deployment integration.`,
		);
	}

	if (settings.buildOutput === 'server' && adapter.adapterFeatures?.buildOutput === 'static') {
		// If the adapter is not compatible with the build output, throw an error
		if (command === 'build') {
			const adapterRecommendation = getAdapterStaticRecommendation(adapter.name);

			throw new AstroError({
				...AstroErrorData.AdapterSupportOutputMismatch,
				message: AstroErrorData.AdapterSupportOutputMismatch.message(adapter.name),
				hint: adapterRecommendation ? adapterRecommendation : undefined,
			});
		} else if (command === 'dev') {
			logger.warn(
				null,
				`The adapter ${adapter.name} does not support emitting a server output, but the project contain server-rendered pages. Your project will not build correctly.`,
			);
		}
	}

	if (adapter.entrypointResolution === undefined) {
		logger.warn(
			null,
			`The adapter ${adapter.name} uses \`entrypointResolution: "explicit"\` by default, which is deprecated and will be removed in a future major version.`,
		);
		logger.warn(

View on GitHub (pinned to 52e6c34790)