withastro/astro · error · Error

[preview] The ${settings.adapter.name} adapter does not supp

Error message

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

What it means

Thrown by preview when an adapter is configured but it does not expose a previewEntrypoint. Not all adapters implement local previewing (some target serverless platforms where local preview is meaningless), so preview refuses to run if the entrypoint is absent.

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

Solutions

Upgrade the adapter to a version that provides previewEntrypoint.
Use an adapter that supports local preview (e.g. @astrojs/node for standalone preview).
Preview the static client build separately, or deploy to a staging environment if local preview is unsupported.

Example fix

// before - adapter without preview support
// (serverless adapter, no previewEntrypoint)
astro preview  // throws

// after
npx astro add node  // switch to node adapter for local preview
astro build && astro preview

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the adapter supports preview before running it.
const adapter = settings.adapter;
if (!adapter?.previewEntrypoint) {
  throw new Error(`${adapter?.name ?? 'adapter'} does not support preview`);
}

Type guard

function adapterSupportsPreview(adapter: { previewEntrypoint?: unknown } | undefined): boolean {
  return Boolean(adapter?.previewEntrypoint);
}

Prevention

Choose an adapter that supports local preview (e.g. @astrojs/node) when you need preview.
Upgrade adapters to versions that ship previewEntrypoint.
For serverless adapters, deploy to a staging env instead of using preview.

When it happens

Trigger: Running `astro preview` with an adapter whose previewEntrypoint is undefined/falsy. The check `if (!settings.adapter.previewEntrypoint)` fires after confirming an adapter exists.

Common situations: Using a serverless adapter (e.g. certain versions of cloudflare/vercel/netlify) that omits preview support; an older adapter version that predates previewEntrypoint; a custom adapter not implementing the preview hook.

Related errors

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