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

In the runnable dev environment, Astro maps every non-redirect route's route.component to a lazy import in the manifest's pageMap. This internal error is thrown when a matched route has no entry in that map — the router and the module map disagree about the route's component. It indicates a dev-server state problem (stale manifest, mid-HMR inconsistency) rather than a user code error.

Source

Thrown at packages/astro/src/vite-plugin-app/environment.ts:81

async function getModuleForRoute(
	manifest: SSRManifest,
	route: RouteData,
): Promise<SinglePageBuiltModule> {
	for (const defaultRoute of getDefaultRoutes(manifest)) {
		if (route.component === defaultRoute.component) {
			return {
				page: () => Promise.resolve(defaultRoute.instance),
			};
		}
	}

	if (route.type === 'redirect') {
		return RedirectSinglePageBuiltModule;
	} else {
		if (manifest.pageMap) {
			const importComponentInstance = manifest.pageMap.get(route.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.",
		);
	}
}

/**
 * The runnable dev environment (the Vite SSR environment can load modules at
 * runtime). The ModuleLoader and AstroSettings are captured in this closure at
 * composition time (`createAstroServerApp`) and are unreachable from
 * requests/states by design — only the environment functions close over them.

View on GitHub (pinned to 52e6c34790)

Solutions

  1. Restart the dev server — this rebuilds the page map and resolves the invariant break
  2. Stop the server, delete node_modules/.vite and .astro caches, then start again
  3. If an integration injects routes, make sure it registers them during config:setup via injectRoute before any request
  4. If it reproduces reliably on the latest Astro, open an issue with your route structure
Defensive patterns

Strategy: try-catch

Try / catch

try {
	const mod = await app.getModuleForRoute(route); // or render via the dev app
} catch (err) {
	if (err instanceof Error && err.message.includes('Unexpectedly unable to find a component instance')) {
		// dev-manifest race: restart the dev server / clear node_modules/.vite, then retry once
	}
	throw err;
}

Prevention

When it happens

Trigger: A request racing route invalidation while pages are being added/renamed under a running dev server; a route injected by an integration whose component never got registered in the page map; context.rewrite() to a route the dev manifest has not materialized; a stale node_modules/.vite cache after upgrading Astro.

Common situations: Renaming or moving files in src/pages while the dev server is running; integrations injecting virtual routes; switching git branches with the dev server up.

Related errors

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