withastro/astro · error · Error

Could not find server component name ${componentPath}

Error message

Could not find server component name ${componentPath}

What it means

Thrown while rendering a server island (a component using the experimental server:defer directive). Before rendering the deferred content, Astro resolves the island component's file path to an internal component id via a name map (serverIslandNameMap) generated by the server-islands Vite plugin at build time. This error means the map returned nothing for that component path, so Astro cannot load the island's server-side implementation. It almost always indicates a mismatch between the compiled page and the generated island manifest, not a mistake in the page markup.

Source

Thrown at packages/astro/src/runtime/server/render/server-islands.ts:134

	async getHostId() {
		if (!this.hostId) {
			this.hostId = await crypto.randomUUID();
		}
		return this.hostId;
	}

	async getIslandContent() {
		if (this.islandContent) {
			return this.islandContent;
		}

		const componentPath = this.getComponentPath();
		const componentExport = this.getComponentExport();
		const serverIslandNameMap = await this.result.getServerIslandNameMap();
		let componentId = serverIslandNameMap.get(componentPath);
		if (!componentId) {
			throw new Error(`Could not find server component name ${componentPath}`);
		}

		// Remove internal props
		for (const key of Object.keys(this.props)) {
			if (internalProps.has(key)) {
				delete this.props[key];
			}
		}

		// Render the slots
		const renderedSlots: Record<string, string> = {};
		for (const name in this.slots) {
			if (name !== 'fallback') {
				const content = await renderSlotToString(this.result, this.slots[name]);
				// renderSlotToString returns a SlotString (typed as string) whose
				// `chunks` hold the ordered content stream. Scripts live inline there,
				// so walking it keeps them at their original position in the island
				// response instead of being appended at the end.

View on GitHub (pinned to 52e6c34790)

Solutions

  1. Update astro and your deployment adapter (@astrojs/node, etc.) to the latest versions so both sides generate and consume the server island name map, then rebuild from a clean state
  2. Delete stale build output (dist/, .astro/) and the Vite cache (node_modules/.vite), then build again
  3. If you render through a custom SSR entrypoint, make sure the manifest passed to the app includes serverIslandNameMap from the built virtual module
  4. If it reproduces on current versions with experimental.serverIslands enabled, file an Astro issue with a minimal reproduction
Defensive patterns

Strategy: try-catch

Try / catch

try {
	const response = await app.render(request);
} catch (err) {
	if (err instanceof Error && err.message.includes('Could not find server component name')) {
		// island name map is stale: clean build output, align astro/adapter versions, rebuild
	}
	throw err;
}

Prevention

When it happens

Trigger: A page uses <Comp server:defer /> but the SSR manifest's serverIslandNameMap is missing or empty (the plugin that generates it substitutes new Map() in environments it does not handle); rendering such a page through a custom SSR entrypoint or adapter that did not include the map; stale build output where the page was compiled by a different Astro version than the runtime serving it.

Common situations: Upgrading Astro while deployed build output is from an older version; enabling experimental.serverIslands with an adapter that predates them; rendering via a custom app/container that bypasses the generated virtual module; leftover dist/ or .astro cache after switching branches or versions.

Related errors

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/27205c186212727d. Report an issue: GitHub.