withastro/astro · critical · AstroError

The server entrypoint ${fileURLToPath(preview.serverEntrypoi

Error message

The server entrypoint ${fileURLToPath(preview.serverEntrypoint)} does not exist. Have you ran a build yet?

What it means

Thrown by the @astrojs/node preview server when Node's dynamic `import()` of the server entry fails with `ERR_MODULE_NOT_FOUND` for the exact `serverEntrypoint` URL. It means the built server bundle file is not on disk where preview expects it.

Source

Thrown at packages/integrations/node/src/preview.ts:27

const createPreviewServer: CreatePreviewServer = async (preview) => {
	let ssrHandler: ServerModule['handler'];
	try {
		process.env.ASTRO_NODE_AUTOSTART = 'disabled';
		const ssrModule: MaybeServerModule = await import(preview.serverEntrypoint.toString());
		if (typeof ssrModule.handler === 'function') {
			ssrHandler = ssrModule.handler;
		} else {
			throw new AstroError(
				`The server entrypoint doesn't have a handler. Are you sure this is the right file?`,
			);
		}
	} catch (err) {
		if (
			(err as any).code === 'ERR_MODULE_NOT_FOUND' &&
			(err as any).url === preview.serverEntrypoint.href
		) {
			throw new AstroError(
				`The server entrypoint ${fileURLToPath(
					preview.serverEntrypoint,
				)} does not exist. Have you ran a build yet?`,
			);
		} else {
			throw err;
		}
	}
	// If the user didn't specify a host, it will already have been defaulted to
	// "localhost" by getResolvedHostForHttpServer in astro core/preview/util.ts.
	// The value `undefined` actually means that either the user set `options.server.host`
	// to `true`, or they passed `--host` without an argument. In that case, we
	// should listen on all IPs.
	const host = process.env.HOST ?? preview.host ?? '0.0.0.0';

	const port = preview.port ?? 4321;
	const server = createServer(ssrHandler, host, port);

View on GitHub (pinned to d081033d5f)

Solutions

1. Run `astro build` first, then `astro preview`.
2. Confirm `build.server` and `outDir` in `astro.config` resolve to the directory you are previewing from.
3. Check that no `.gitignore`/CI cleanup removed `dist/` after the build step.

Example fix

# before
astro preview   # without a prior build
# after
astro build && astro preview

import { existsSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
const entry = fileURLToPath(serverEntrypoint);
if (!existsSync(entry)) {
  throw new Error(`Build output missing: ${entry}. Run 'astro build' first.`);
}

When it happens

Trigger: Running `astro preview` before `astro build`, or after deleting/moving `dist/`. The preview server resolves `preview.serverEntrypoint` (typically `dist/server/entry.mjs`) and the file is absent.

Common situations: Fresh clone where only sources are present. A `clean`/`rimraf dist` step run between build and preview. Wrong `outDir`/`build.server` config so the file lands elsewhere.

Related errors

• The server entrypoint doesn't have a handler. Are you sure t
• [preview] The output directory ${outDirPath} does not exist.
• CannotDetermineWeightAndStyleFromFontFile
• UnknownFilesystemError
• UnknownFilesystemError

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