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 at build time when the project's detected build output is `server` (it contains server-rendered pages) but the configured adapter declares `adapterFeatures.buildOutput === 'static'`. The adapter cannot emit server output, so the build would be broken; Astro fails fast with a hint pointing to a recommended server adapter. In dev the same condition only warns.

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 d081033d5f)

Solutions

1. Install and configure a server-capable adapter (e.g., `@astrojs/node`, `@astrojs/vercel/serverless`) — the hint suggests a recommendation.
2. If you intend static output, remove server-rendered pages and set `output: 'static'`.
3. Confirm the adapter's `adapterFeatures.buildOutput` is `'server'` or `'hybrid'` for server projects.

Example fix

// before
import staticAdapter from '@astrojs/static-host';
export default defineConfig({ adapter: staticAdapter(), output: 'server' });

// after
import node from '@astrojs/node';
export default defineConfig({ adapter: node({ mode: 'standalone' }), output: 'server' });

const serverOutput = settings.buildOutput === 'server';
const staticAdapter = adapter.adapterFeatures?.buildOutput === 'static';
if (serverOutput && staticAdapter) throw new Error('Adapter cannot emit server output');

function adapterSupportsServer(adapter) { return adapter?.adapterFeatures?.buildOutput !== 'static'; }

When it happens

Trigger: Using a static-only adapter (e.g., a static-host adapter) while a page has `export const prerender = false` or `output: 'server'`, then running `astro build`. The branch at `adapter-validation.ts:38` throws during `command === 'build'`.

Common situations: Switching a project from static to hybrid/server output without changing the adapter; installing a static adapter by mistake; an adapter that hasn't opted into server output features.

Related errors

• Integration "${maybeConflictingIntegration}" conflicts with
• ClientAddressNotAvailable
• Action not found: ${path}
• CannotOptimizeSvg
• RemoteImageNotAllowed

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