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 dev fallback (`dev-nonrunnable.ts`) route modules are looked up in `manifest.pageMap` keyed by `route.component`; a missing key means the internal routing manifest is out of sync with the requested route — an internal invariant violation, not a user configuration error. Redirect routes are handled before this check, so only mapped page routes reach it.

Source

Thrown at packages/astro/src/core/environment/dev-nonrunnable.ts:47

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.",
		);
	}
}

async function getComponentByRoute(
	manifest: SSRManifest,
	routeData: RouteData,
): Promise<ComponentInstance> {
	try {

View on GitHub (pinned to 52e6c34790)

Solutions

Restart the dev server so the route manifest is rebuilt from disk.
Stop stale servers first (`astro dev stop` or kill the process), then start again.
If it persists, delete the `.astro` cache directory and restart.
Still reproducible on latest versions? File an Astro issue with the route pattern and steps.

Example fix

# before
Error: Unexpectedly unable to find a component instance for route /renamed-page

# after — restart to rebuild the route manifest
pnpm -C . dev stop && pnpm -C . dev

Defensive patterns

Strategy: retry

Try / catch

// Tooling that drives the dev environment: a stale manifest recovers on restart
try {
  await renderRoute(route);
} catch (err) {
  if (err instanceof Error && err.message.includes('component instance for route')) {
    await restartDevServer(); // rebuilds pageMap from disk
    return renderRoute(route);
  }
  throw err;
}

Prevention

Restart the dev server after bulk renames/moves under src/pages.
Stop stale servers (`astro dev stop`) before starting a new one on the same root.
Report routes that reliably reproduce after a clean restart.

When it happens

Trigger: Dev-time manifest desync: a page was renamed/moved/added while the running dev server still holds a stale manifest, or a race between file change and route collection left `pageMap` without an entry for the requested route.

Common situations: Renaming or bulk-moving files in `src/pages` while `astro dev` is running; an interrupted sync/HMR update; leftover processes from a previous session holding the lock.

Related errors

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