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

Server islands require a deployment adapter, just like SSR. The server-islands Vite plugin throws AstroError code NoAdapterInstalledServerIslands from its handler when a compiled .astro/.mdx module declares a server component (server: prefixed import) but settings.adapter is unset.

Source

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

			},
		},

		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 d081033d5f)

Solutions

Install and configure an adapter, e.g. `npx astro add node` then set output accordingly.
Remove the `server:` prefix from the import to render it as a normal static/client component.
Confirm settings.adapter is set in the active astro.config (check for config merge issues).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

import config from './astro.config.mjs';
if (!config.adapter) {
  throw new Error('A server adapter is required when using server islands (server: imports).');
}

Type guard

import type { AstroIntegration } from 'astro';
const hasAdapter = (cfg: { adapter?: AstroIntegration }): boolean => !!cfg.adapter;

Prevention

Add an adapter (`astro add node`) before introducing server islands.
Treat `server:` imports as SSR-only and gate them behind adapter config.
Run a CI build to catch missing adapters early.

When it happens

Trigger: Using `import Login from '../Login.vue server:import';` (a server island) in an .astro page while no adapter is configured in astro.config.

Common situations: Experimenting with server islands on a project still in static mode; adding `server:` imports before wiring an adapter; CI build with a different config than local.

Related errors

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