withastro/astro · error · AstroError

NoAdapterInstalledServerIslands

NoAdapterInstalledServerIslands

Error message

Cannot use server islands without an adapter. Please install and configure the appropriate server adapter for your final deployment.

What it means

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.

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.

Example fix

// before (astro.config.mjs)
export default defineConfig({ output: 'static' });
// page still contains: <UserInfo server:defer />

// after
import node from '@astrojs/node';
export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Defensive patterns

Strategy: validation

Validate before calling

// astro.config.mjs
import { defineConfig } from 'astro/config';

const config = defineConfig({});
if (!config.adapter) {
  // fail your own prebuild check before any server:defer usage ships
  console.warn('No adapter: server:defer components will fail to compile');
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of withastro/astro@e294953aa8 (2026-08-18). Data as JSON: /api/errors/7820651bfab26287. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/core/server-islands/vite-plugin-server-islands.ts:108

			},
		},

		transform: {
			filter: {
				id: {
					include: [/\.(astro|mdx)$/, new RegExp(`^${RESOLVED_SERVER_ISLAND_MANIFEST}$`)],
				},
			},
			async handler(_code, id) {
				const info = this.getModuleInfo(id);
				const astro = info ? (info.meta.astro as AstroPluginMetadata['astro']) : undefined;
				const isBuildSsr =
					command === 'build' && this.environment?.name === ASTRO_VITE_ENVIRONMENT_NAMES.ssr;

				if (astro) {
					for (const comp of astro.serverComponents) {
						if (!settings.adapter) {
							throw new AstroError(AstroErrorData.NoAdapterInstalledServerIslands);
						}

						const island = serverIslandsState.discover({
							resolvedPath: comp.resolvedPath,
							localName: comp.localName,
							specifier: comp.specifier ?? comp.resolvedPath,
							importer: id,
						});

						if (isBuildSsr && !serverIslandsState.hasReferenceId(comp.resolvedPath)) {
							const referenceId = this.emitFile({
								type: 'chunk',
								id: island.specifier,
								importer: island.importer,
								name: island.islandName,
							});
							serverIslandsState.setReferenceId(comp.resolvedPath, referenceId);
						}

View on GitHub (pinned to e294953aa8)