{"record":{"id":"48c0d9eff6bccdba","repo":"withastro/astro","slug":"the-server-entrypoint-doesn-t-have-a-handler-are","errorCode":null,"errorMessage":"The server entrypoint doesn't have a handler. Are you sure this is the right file?","messagePattern":"The server entrypoint doesn't have a handler\\. Are you sure this is the right file\\?","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"critical","filePath":"packages/integrations/node/src/preview.ts","lineNumber":18,"sourceCode":"import { fileURLToPath } from 'node:url';\nimport type { CreatePreviewServer } from 'astro';\nimport { AstroError } from 'astro/errors';\nimport { logListeningOn } from './log-listening-on.js';\nimport { createServer } from './standalone.js';\n\ntype ServerModule = typeof import('./server.js');\ntype MaybeServerModule = Partial<ServerModule>;\n\nconst createPreviewServer: CreatePreviewServer = async (preview) => {\n\tlet ssrHandler: ServerModule['handler'];\n\ttry {\n\t\tprocess.env.ASTRO_NODE_AUTOSTART = 'disabled';\n\t\tconst ssrModule: MaybeServerModule = await import(preview.serverEntrypoint.toString());\n\t\tif (typeof ssrModule.handler === 'function') {\n\t\t\tssrHandler = ssrModule.handler;\n\t\t} else {\n\t\t\tthrow new AstroError(\n\t\t\t\t`The server entrypoint doesn't have a handler. Are you sure this is the right file?`,\n\t\t\t);\n\t\t}\n\t} catch (err) {\n\t\tif (\n\t\t\t(err as any).code === 'ERR_MODULE_NOT_FOUND' &&\n\t\t\t(err as any).url === preview.serverEntrypoint.href\n\t\t) {\n\t\t\tthrow new AstroError(\n\t\t\t\t`The server entrypoint ${fileURLToPath(\n\t\t\t\t\tpreview.serverEntrypoint,\n\t\t\t\t)} does not exist. Have you ran a build yet?`,\n\t\t\t);\n\t\t} else {\n\t\t\tthrow err;\n\t\t}\n\t}\n\t// If the user didn't specify a host, it will already have been defaulted to","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/integrations/node/src/preview.ts#L1-L36","documentation":"Thrown by the @astrojs/node preview server when the dynamically imported server entry module has no `handler` export. The preview server needs `handler` to forward HTTP requests to the built Astro app; a module without it is almost certainly the wrong file.","triggerScenarios":"Running `astro preview` when the built `dist/server/entry.mjs` (the configured `serverEntrypoint`) does not export a function named `handler`. This happens if the adapter/server entry path was overridden, or a custom build emitted a differently-shaped entry.","commonSituations":"Pointing the preview at a hand-rolled server file. A bundler config that renamed or wrapped the default export. Mixing adapter versions where an older server entry used a different export name.","solutions":["Re-run `astro build` so the adapter regenerates `dist/server/entry.mjs` with the correct `handler` export.","Verify nothing overrides `adapter.serverEntrypoint`; the default `@astrojs/node/server.js` is what emits `handler`.","If you customize the server entry, ensure it does `export const handler = createHandler(...)` (or `export { handler }`)."],"exampleFix":"// before: custom server.ts exporting `export default app`\n// after: custom server.ts\nexport const handler = app;\nexport default app;","handlingStrategy":"try-catch","validationCode":"const mod = await import(serverEntryUrl);\nif (typeof mod.handler !== 'function') {\n  throw new Error(`Refusing to start preview: ${serverEntryUrl} has no handler export`);\n}","typeGuard":"function isServerModule(m: unknown): m is { handler: (req: unknown, res: unknown) => void } {\n  return !!m && typeof (m as any).handler === 'function';\n}","tryCatchPattern":"try { await import(entry); } catch (e) {\n  if (/doesn't have a handler/) { /* re-run build or fix entry */ }\n  else throw e;\n}","preventionTips":["Always run `astro build` before `astro preview`.","Do not override the adapter's `serverEntrypoint` unless your custom entry exports `handler`.","Pin the @astrojs/node version so the entry shape stays stable."],"tags":["node-adapter","preview","build-output","entrypoint"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}