{"record":{"id":"bdb866b8ad115b0d","repo":"withastro/astro","slug":"unexpectedly-unable-to-find-a-component-instance-f-bdb866","errorCode":null,"errorMessage":"Unexpectedly unable to find a component instance for route ${route.route}","messagePattern":"Unexpectedly unable to find a component instance for route (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/astro/src/vite-plugin-app/environment.ts","lineNumber":81,"sourceCode":"async function getModuleForRoute(\n\tmanifest: SSRManifest,\n\troute: RouteData,\n): Promise<SinglePageBuiltModule> {\n\tfor (const defaultRoute of getDefaultRoutes(manifest)) {\n\t\tif (route.component === defaultRoute.component) {\n\t\t\treturn {\n\t\t\t\tpage: () => Promise.resolve(defaultRoute.instance),\n\t\t\t};\n\t\t}\n\t}\n\n\tif (route.type === 'redirect') {\n\t\treturn RedirectSinglePageBuiltModule;\n\t} else {\n\t\tif (manifest.pageMap) {\n\t\t\tconst importComponentInstance = manifest.pageMap.get(route.component);\n\t\t\tif (!importComponentInstance) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Unexpectedly unable to find a component instance for route ${route.route}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn await importComponentInstance();\n\t\t} else if (manifest.pageModule) {\n\t\t\treturn manifest.pageModule;\n\t\t}\n\t\tthrow new Error(\n\t\t\t\"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.\",\n\t\t);\n\t}\n}\n\n/**\n * The runnable dev environment (the Vite SSR environment can load modules at\n * runtime). The ModuleLoader and AstroSettings are captured in this closure at\n * composition time (`createAstroServerApp`) and are unreachable from\n * requests/states by design — only the environment functions close over them.","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/withastro/astro/blob/52e6c34790cc8ac4e69e6135ace06049867e5c4a/packages/astro/src/vite-plugin-app/environment.ts#L63-L99","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restart the dev server — this rebuilds the page map and resolves the invariant break","Stop the server, delete node_modules/.vite and .astro caches, then start again","If an integration injects routes, make sure it registers them during config:setup via injectRoute before any request","If it reproduces reliably on the latest Astro, open an issue with your route structure"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n\tconst mod = await app.getModuleForRoute(route); // or render via the dev app\n} catch (err) {\n\tif (err instanceof Error && err.message.includes('Unexpectedly unable to find a component instance')) {\n\t\t// dev-manifest race: restart the dev server / clear node_modules/.vite, then retry once\n\t}\n\tthrow err;\n}","preventionTips":["Restart the dev server after renaming or moving files in src/pages","Register injected routes in injectRoute during config:setup, never at request time","Clear node_modules/.vite and .astro caches after upgrading Astro"],"tags":["internal","dev-server","routing","manifest"],"backgroundTag":"ssr-route-resolution-failed","analyzedSha":"52e6c34790cc8ac4e69e6135ace06049867e5c4a","analyzedAt":"2026-08-18T18:48:03.901Z","contentChangedAt":"2026-08-18T18:48:03.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}