withastro/astro · error · Error

[preview] The adapter does not support the preview command.

Error message

[preview] The ${settings.adapter.name} adapter does not support the preview command.

What it means

After confirming an adapter exists, `astro preview` requires it to expose a `previewEntrypoint` — the module Astro imports to create the local preview server. Some adapters (especially those targeting edge/serverless platforms, older versions, or minimal custom adapters) deliberately omit it because their platform serves the built output instead. Preview throws naming the adapter when the property is missing.

Solutions

Deploy the built output to the adapter's platform instead of using `astro preview` (that is the intended verification path for such adapters)
Add the Node adapter (`npx astro add node`) when you need a local preview server, and swap back for deployment
Update the adapter to the latest version — preview support may have been added
For a custom adapter, implement `previewEntrypoint` exporting a default function that starts a server

Example fix

# before
astro preview   # throws: The <adapter> adapter does not support the preview command.

# after — verify locally with the node adapter
npx astro add node
astro build && astro preview
# or skip preview and deploy the adapter's build output to its platform

Defensive patterns

Strategy: type-guard

Validate before calling

// before wiring a custom/edge adapter, check its capabilities
import myAdapter from './my-adapter.js';
export default defineConfig({
  adapter: supportsPreview(myAdapter) ? myAdapter : undefined,
});

Type guard

// AstroAdapter shape check — does this adapter implement local preview?
import type { AstroAdapter } from 'astro';
export function supportsPreview(adapter?: AstroAdapter): boolean {
  return typeof adapter?.previewEntrypoint === 'string';
}

Prevention

Before adopting an adapter, check its README for `preview` support (or run `astro preview` once as a smoke test)
Keep @astrojs/node available as a local-verification fallback for platform-targeted adapters
For custom adapters, implement `previewEntrypoint` with a default-exported function from day one

When it happens

Trigger: Running `astro preview` with an adapter that targets a deploy platform rather than local serving (older Vercel/Cloudflare edge adapters, community adapters without preview support); a custom adapter that only implements `serverEntrypoint`/`exports` and forgot preview; an outdated adapter version predating preview support.

Common situations: Trying to verify an SSR build locally before deploying to a serverless platform; upgrading Astro but keeping an old adapter major version; writing an in-house adapter and testing `astro build` + `astro preview` for the first time.

Related errors

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

Appendix: source

Thrown at packages/astro/src/core/preview/index.ts:67

	if (settings.buildOutput === 'static' && !settings.adapter?.previewEntrypoint) {
		const clientOutDir = getClientOutputDirectory(settings);
		if (!fs.existsSync(clientOutDir)) {
			const outDirPath = fileURLToPath(clientOutDir);
			throw new Error(
				`[preview] The output directory ${outDirPath} does not exist. Did you run \`astro build\`?`,
			);
		}
		const server = await createStaticPreviewServer(settings, logger);
		return server;
	}

	if (!settings.adapter) {
		throw new Error(`[preview] No adapter found.`);
	}

	if (!settings.adapter.previewEntrypoint) {
		throw new Error(
			`[preview] The ${settings.adapter.name} adapter does not support the preview command.`,
		);
	}
	// We need to use require.resolve() here so that advanced package managers like pnpm
	// don't treat this as a dependency of Astro itself. This correctly resolves the
	// preview entrypoint of the integration package, relative to the user's project root.
	const require = createRequire(settings.config.root);
	const previewEntrypointUrl = pathToFileURL(
		require.resolve(settings.adapter.previewEntrypoint.toString()),
	).href;

	const previewModule = (await import(previewEntrypointUrl)) as Partial<PreviewModule>;
	if (typeof previewModule.default !== 'function') {
		throw new Error(`[preview] ${settings.adapter.name} cannot preview your app.`);
	}

	const server = await previewModule.default({
		outDir: settings.config.outDir,

View on GitHub (pinned to 52e6c34790)