{"record":{"id":"7820651bfab26287","repo":"withastro/astro","slug":"noadapterinstalledserverislands","errorCode":"NoAdapterInstalledServerIslands","errorMessage":"Cannot use server islands without an adapter. Please install and configure the appropriate server adapter for your final deployment.","messagePattern":"Cannot use server islands without an adapter\\. Please install and configure the appropriate server adapter for your final deployment\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/core/server-islands/vite-plugin-server-islands.ts","lineNumber":108,"sourceCode":"\t\t\t},\n\t\t},\n\n\t\ttransform: {\n\t\t\tfilter: {\n\t\t\t\tid: {\n\t\t\t\t\tinclude: [/\\.(astro|mdx)$/, new RegExp(`^${RESOLVED_SERVER_ISLAND_MANIFEST}$`)],\n\t\t\t\t},\n\t\t\t},\n\t\t\tasync handler(_code, id) {\n\t\t\t\tconst info = this.getModuleInfo(id);\n\t\t\t\tconst astro = info ? (info.meta.astro as AstroPluginMetadata['astro']) : undefined;\n\t\t\t\tconst isBuildSsr =\n\t\t\t\t\tcommand === 'build' && this.environment?.name === ASTRO_VITE_ENVIRONMENT_NAMES.ssr;\n\n\t\t\t\tif (astro) {\n\t\t\t\t\tfor (const comp of astro.serverComponents) {\n\t\t\t\t\t\tif (!settings.adapter) {\n\t\t\t\t\t\t\tthrow new AstroError(AstroErrorData.NoAdapterInstalledServerIslands);\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tconst island = serverIslandsState.discover({\n\t\t\t\t\t\t\tresolvedPath: comp.resolvedPath,\n\t\t\t\t\t\t\tlocalName: comp.localName,\n\t\t\t\t\t\t\tspecifier: comp.specifier ?? comp.resolvedPath,\n\t\t\t\t\t\t\timporter: id,\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\tif (isBuildSsr && !serverIslandsState.hasReferenceId(comp.resolvedPath)) {\n\t\t\t\t\t\t\tconst referenceId = this.emitFile({\n\t\t\t\t\t\t\t\ttype: 'chunk',\n\t\t\t\t\t\t\t\tid: island.specifier,\n\t\t\t\t\t\t\t\timporter: island.importer,\n\t\t\t\t\t\t\t\tname: island.islandName,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tserverIslandsState.setReferenceId(comp.resolvedPath, referenceId);\n\t\t\t\t\t\t}","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/withastro/astro/blob/e294953aa8aadd98d5be92e60a03037b05dbdfd4/packages/astro/src/core/server-islands/vite-plugin-server-islands.ts#L90-L126","documentation":"A server island (a component rendered with the server:defer directive) is hydrated by making a request back to the Astro server at runtime, so it only works with on-demand rendering provided by a server adapter. The server-islands Vite plugin scans each compiled .astro/.mdx module's metadata (astro.serverComponents) and throws NoAdapterInstalledServerIslands during transform when a deferred server component is found and settings.adapter is unset — i.e. in a static-output project with no adapter.","triggerScenarios":"Marking a component with the server island directive in an .astro or .mdx file, e.g. <UserInfo server:defer />, while astro.config has no adapter (default output: 'static'). The throw happens at dev-server transform / build compile time, as soon as the containing page is processed.","commonSituations":"Adding a personalized widget to a mostly-static marketing site without having run astro add node; following a server-islands tutorial in a fresh static project; removing the adapter integration later while pages still contain server:defer components.","solutions":["Install and configure an adapter: npx astro add node (or the adapter for your platform, e.g. @astrojs/vercel, @astrojs/cloudflare).","If the component does not need per-request server rendering, remove the server:defer directive so it renders at build time.","Verify the adapter appears in astro.config.mjs integrations/export default defineConfig({ adapter: ... }) after installation."],"exampleFix":"// before (astro.config.mjs)\nexport default defineConfig({ output: 'static' });\n// page still contains: <UserInfo server:defer />\n\n// after\nimport node from '@astrojs/node';\nexport default defineConfig({\n  output: 'server',\n  adapter: node({ mode: 'standalone' }),\n});","handlingStrategy":"validation","validationCode":"// astro.config.mjs\nimport { defineConfig } from 'astro/config';\n\nconst config = defineConfig({});\nif (!config.adapter) {\n  // fail your own prebuild check before any server:defer usage ships\n  console.warn('No adapter: server:defer components will fail to compile');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["server:defer requires output:'server' plus an adapter — set both up (npx astro add node) before adding the directive.","Keep a code-search rule (grep server:defer) in CI that fails when the directive exists but no adapter is configured.","If you remove the adapter later, remove every server:defer usage in the same change."],"tags":["astro","server-islands","adapter","ssr","build-time","vite-plugin"],"backgroundTag":"missing-server-adapter","analyzedSha":"e294953aa8aadd98d5be92e60a03037b05dbdfd4","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}