{"record":{"id":"395ef1ed35e9b35e","repo":"withastro/astro","slug":"preview-settings-adapter-name-cannot-preview","errorCode":null,"errorMessage":"[preview] ${settings.adapter.name} cannot preview your app.","messagePattern":"\\[preview\\] (.+?) cannot preview your app\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/preview/index.ts","lineNumber":81,"sourceCode":"\t\tthrow new Error(`[preview] No adapter found.`);\n\t}\n\n\tif (!settings.adapter.previewEntrypoint) {\n\t\tthrow new Error(\n\t\t\t`[preview] The ${settings.adapter.name} adapter does not support the preview command.`,\n\t\t);\n\t}\n\t// We need to use require.resolve() here so that advanced package managers like pnpm\n\t// don't treat this as a dependency of Astro itself. This correctly resolves the\n\t// preview entrypoint of the integration package, relative to the user's project root.\n\tconst require = createRequire(settings.config.root);\n\tconst previewEntrypointUrl = pathToFileURL(\n\t\trequire.resolve(settings.adapter.previewEntrypoint.toString()),\n\t).href;\n\n\tconst previewModule = (await import(previewEntrypointUrl)) as Partial<PreviewModule>;\n\tif (typeof previewModule.default !== 'function') {\n\t\tthrow new Error(`[preview] ${settings.adapter.name} cannot preview your app.`);\n\t}\n\n\tconst server = await previewModule.default({\n\t\toutDir: settings.config.outDir,\n\t\tclient: settings.config.build.client,\n\t\tserver: settings.config.build.server,\n\t\tserverEntrypoint: new URL(settings.config.build.serverEntry, settings.config.build.server),\n\t\thost: getResolvedHostForHttpServer(settings.config.server.host),\n\t\tport: settings.config.server.port,\n\t\tbase: settings.config.base,\n\t\tlogger: new AstroIntegrationLogger(logger.options, settings.adapter.name),\n\t\theaders: settings.config.server.headers,\n\t\tallowedHosts: settings.config.server.allowedHosts,\n\t\topen: settings.config.server.open,\n\t\troot: settings.config.root,\n\t});\n\n\treturn server;","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/core/preview/index.ts#L63-L99","documentation":"Preview resolves the adapter's `previewEntrypoint` with `require.resolve()` relative to the project root (so package managers like pnpm do not hoist it into Astro), imports it as a module, and calls its default export to obtain the server. If that module's default export is anything other than a function, the adapter contract is broken — usually a malformed custom adapter, a broken package publish, or a version mismatch — and preview aborts.","triggerScenarios":"A custom adapter whose preview entrypoint uses a named export (`export const preview`) or an object instead of `export default`; a partially published or corrupted adapter package where the entrypoint resolves to the wrong file (exports-map mismatch); an adapter version whose preview API predates the current Astro runtime.","commonSituations":"Authoring a first-party adapter and forgetting the default-export convention; mixing an adapter built for an older Astro with a newer core; a bad install (half-written files) after an interrupted npm/pnpm install.","solutions":["Reinstall dependencies (`rm -rf node_modules && npm install` or `pnpm install`) to rule out a corrupted package","Upgrade the adapter to a version compatible with your Astro version","If you maintain the adapter, make the preview entrypoint export a default async function receiving the preview options and returning a server object","Check the adapter package's `exports` map actually points `previewEntrypoint` at the file you think it does"],"exampleFix":"// before — adapter preview entrypoint\nexport const preview = async (options) => { /* start server */ };\n\n// after\nexport default async function preview(options) {\n  const server = http.createServer(/* serve files from options.server outDir */);\n  await new Promise((r) => server.listen(options.port, options.host, r));\n  return { server, closed: false };\n}","handlingStrategy":"type-guard","validationCode":"// adapter smoke test — import the preview entrypoint the way preview does\nimport { pathToFileURL } from 'node:url';\nimport { createRequire } from 'node:module';\nconst req = createRequire(process.cwd() + '/');\nconst mod = await import(pathToFileURL(req.resolve('./my-adapter/preview.js')).href);\nif (typeof mod.default !== 'function') throw new Error('adapter preview entrypoint malformed');","typeGuard":"// Narrow an imported adapter preview module to a callable server factory\nexport function isPreviewModule(m: unknown): m is { default: (opts: any) => Promise<any> } {\n  return typeof (m as any)?.default === 'function';\n}","tryCatchPattern":null,"preventionTips":["Pin adapter versions compatible with your Astro version (check peerDependencies)","When authoring adapters, export `default async function preview(options)` returning `{ server, closed }`","Reinstall node_modules after interrupted installs before debugging adapter load failures"],"tags":["preview","adapter","entrypoint","esm-import"],"backgroundTag":"invalid-adapter-entrypoint","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}