withastro/astro · error · Error

Astro couldn't find the correct page to render, probably…

Error message

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.

What it means

The last-resort branch in the dev fallback: the manifest has neither a `pageMap` entry for the route nor a `pageModule`, so Astro cannot map the route to any renderable module and throws this internal error asking you to file an issue. It indicates an incomplete SSR manifest in the dev environment, not a mistake in your pages.

Solutions

Restart the dev server (and clear `.astro/`) to regenerate the manifest.
If you maintain a custom environment, make sure its manifest sets `pageMap` (route.component → import) or a `pageModule`.
Reduce to a minimal repro and file an Astro issue if it happens with stock configuration.

Defensive patterns

Strategy: fallback

Validate before calling

// Custom environments: ensure the manifest you hand to the renderer is complete
const manifest = {
  pageMap: new Map(routes.map((r) => [r.component, () => import(r.component)])),
  // or: pageModule for single-entry setups
};

Type guard

function isRenderableManifest(m: { pageMap?: Map<string, unknown>; pageModule?: unknown }): boolean {
  return m.pageMap instanceof Map || m.pageModule !== undefined;
}

Try / catch

try {
  await getComponentByRoute(manifest, routeData);
} catch (err) {
  if (err instanceof Error && err.message.includes("correct page to render")) {
    // recover by rebuilding the dev manifest rather than crashing the request
    await triggerDevManifestRebuild();
    return;
  }
  throw err;
}

Prevention

When implementing custom RenderEnvironments, always populate `pageMap` or `pageModule` in the manifest.
Restart dev and clear `.astro/` after large structural refactors.
File internal errors with a minimal repro so the invariant can be fixed upstream.

When it happens

Trigger: A custom or experimental RenderEnvironment whose manifest provides neither `pageMap` nor `pageModule`; dev-manifest corruption after large structural changes (many files moved at once) while the server keeps serving requests.

Common situations: Projects using custom environments that hand-build an SSRManifest; dev races during heavy refactors; bugs in dev-time route collection.

Related errors

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

Appendix: source

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

			};
		}
	}

	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 {
		const module = await getModuleForRoute(manifest, routeData);
		return module.page();
	} catch {
		// could not find, ignore
	}

	const url = new URL(routeData.component, manifest.rootDir);
	const module = await import(/* @vite-ignore */ url.toString());

View on GitHub (pinned to 52e6c34790)