withastro/astro · error · Error

[preview] The output directory ${outDirPath} does not exist.

Error message

[preview] The output directory ${outDirPath} does not exist. Did you run `astro build`?

What it means

Thrown by the preview command (createStaticPreviewServer path) when the build output directory does not exist on disk. Preview serves the already-built static assets, so if `astro build` was never run (or output went elsewhere), the client output directory is missing and preview cannot start.

Source

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

	const settings = await runHookConfigSetup({
		settings: _settings,
		command: 'preview',
		logger: logger,
	});

	// Create a route manifest and determine buildOutput from actual routes.
	// Route scanning sets settings.buildOutput to 'server' if any route is non-prerendered.
	settings.buildOutput = getPrerenderDefault(settings.config) ? 'static' : 'server';
	await createRoutesList({ settings: settings, cwd: inlineConfig.root }, logger);

	await runHookConfigDone({ settings: settings, logger: logger, command: 'preview' });

	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

View on GitHub (pinned to d081033d5f)

Solutions

1. Run `astro build` first, then `astro preview`.
2. Verify `outDir`/`build.client` in astro.config matches where build actually emits.
3. Ensure the build completed successfully (check for build errors) before previewing.

Example fix

// before
astro preview  # dist/ missing

// after
astro build && astro preview

// Verify build output exists before starting preview.
import { existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
const clientDir = fileURLToPath(new URL('dist/client', import.meta.url));
if (!existsSync(clientDir)) {
  throw new Error('Run `astro build` before `astro preview`');
}
// then start preview

When it happens

Trigger: Running `astro preview` for a static (or prerender-default) build when the client output directory (default dist/client or dist) does not exist. The check fs.existsSync(clientOutDir) is false, so the error names the resolved outDirPath.

Common situations: Running preview before build; changing outDir in config so build output goes to a different folder than preview reads; CI/deploy workflows that run preview on a clean checkout without building; a failed/partial build that did not emit the client dir.

Related errors

• CannotDetermineWeightAndStyleFromFontFile
• UnknownFilesystemError
• UnknownFilesystemError
• UnknownFilesystemError
• Failed to write lock file: ${message}

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