withastro/astro · error · Error

Unexpectedly unable to find a component instance for route $

Error message

Unexpectedly unable to find a component instance for route ${route.route}

What it means

The production RenderEnvironment resolves route modules from the built SSRManifest's `pageMap` (after resolving i18n fallback routes). If `route.component` has no entry, it throws this internal error: the running server bundle's manifest does not describe the route it was asked to render. This is a build/deploy desync, not a user code error.

Source

Thrown at packages/astro/src/core/environment/production.ts:48

	}
	let routeToProcess = route;
	if (routeIsRedirect(route)) {
		if (route.redirectRoute) {
			// This is a static redirect
			routeToProcess = route.redirectRoute;
		} else {
			// This is an external redirect, so we return a component stub
			return RedirectSinglePageBuiltModule;
		}
	} else if (routeIsFallback(route)) {
		// This is an i18n fallback route
		routeToProcess = getFallbackRoute(route, manifest.routes);
	}

	if (manifest.pageMap) {
		const importComponentInstance = manifest.pageMap.get(routeToProcess.component);
		if (!importComponentInstance) {
			throw new Error(`Unexpectedly unable to find a component instance for route ${route.route}`);
		}
		return await importComponentInstance();
	} else if (manifest.pageModule) {
		return manifest.pageModule;
	}
	throw new Error(
		"Astro couldn't find the correct page to render, probably because it wasn't correctly mapped for SSR usage. This is an internal error, please file an issue.",
	);
}

async function getComponentByRoute(
	manifest: SSRManifest,
	routeData: RouteData,
): Promise<ComponentInstance> {
	const module = await getModuleForRoute(manifest, routeData);
	return module.page();
}

View on GitHub (pinned to 52e6c34790)

Solutions

Do a clean rebuild (`rm -rf dist && astro build`) and deploy the whole output as one atomic unit.
Verify the deployed manifest actually lists the failing route (inspect the SSR manifest in `dist`).
Update your adapter to the latest version — route filtering bugs land here.
If it reproduces with stock adapters, file an issue with the route and adapter versions.

Example fix

# before — mixed artifacts on the server
# dist/server manifest from build A, pages from build B

# after — clean rebuild, deploy dist as one unit
rm -rf dist && npm run build && npm run deploy

Defensive patterns

Strategy: validation

Validate before calling

// Custom server/integration: verify the deployed manifest knows the route
if (!manifest.pageMap?.has(route.component)) {
  throw new Error(`Deploy mismatch: rebuild and redeploy to serve ${route.route}`);
}
const mod = await getComponentByRoute(manifest, route);

Prevention

Deploy `dist` atomically — never mix artifacts from two builds.
Invalidate CDN/container caches for the manifest when rolling out.
Stamp builds with a version and log it at startup to detect mixed deploys early.

When it happens

Trigger: Partial or mixed deploys where routes and the server manifest come from different builds; a custom adapter that filters or rewrites routes without updating `pageMap`; mixing old `dist` artifacts with new ones (cached Docker layers, incremental upload).

Common situations: Incremental deploys uploading only changed files; CDN/object-store caches serving a stale manifest; custom adapters manipulating the route list; rolling back only half the output.

Related errors

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