withastro/astro · error · AstroError

MissingIndexForInternationalizationError

MissingIndexForInternationalizationError

Error message

Could not find index page. A root index page is required in order to create a redirect to the index URL of the default locale. (`/${defaultLocale}`)

What it means

MissingIndexForInternationalization: with i18n routing strategy 'pathname-prefix-always', Astro builds a redirect from '/' to the default locale's index ('/defaultLocale'). That redirect requires a root index page (route '/'). If no route with route === '/' exists, the redirect target is missing and Astro throws at manifest creation.

Source

Thrown at packages/astro/src/core/routing/create-manifest.ts:774

	// Report route collisions
	for (const [index, higherRoute] of routes.entries()) {
		for (const lowerRoute of routes.slice(index + 1)) {
			detectRouteCollision(higherRoute, lowerRoute, config, logger);
		}
	}

	const i18n = settings.config.i18n;
	if (i18n) {
		const strategy = toRoutingStrategy(i18n.routing, i18n.domains);
		// First we check if the user doesn't have an index page.
		if (strategy === 'pathname-prefix-always') {
			let index = routes.find((route) => route.route === '/');
			if (!index) {
				let relativePath = path.relative(
					fileURLToPath(settings.config.root),
					fileURLToPath(new URL('pages', settings.config.srcDir)),
				);
				throw new AstroError({
					...MissingIndexForInternationalization,
					message: MissingIndexForInternationalization.message(i18n.defaultLocale),
					hint: MissingIndexForInternationalization.hint(relativePath),
				});
			}
		}

		createI18nFallbackRoutes(routes, i18n, config);
	}

	if (dev) {
		// In SSR, a 404 route is injected in the App directly for some special handling,
		// it must not appear in the manifest
		ensure404Route({ routes });
	}
	if (dev || settings.buildOutput === 'server') {
		injectImageEndpoint(settings, { routes }, dev ? 'dev' : 'build');
	}

View on GitHub (pinned to d081033d5f)

Solutions

Create an index page at src/pages/index.astro (or index.md).
If you don't want the auto-redirect, set i18n.routing.prefixDefaultLocale to false.
Verify the root index page resolves to route '/' (check it is not accidentally nested).

Example fix

// before — no src/pages/index.astro, i18n prefixDefaultLocale: true

// after — create src/pages/index.astro
---
<html><body>Home</body></html>

Defensive patterns

Strategy: validation

Validate before calling

function hasRootIndex(routes: { route: string }[]): boolean {
  return routes.some(r => r.route === '/');
}
// when using pathname-prefix-always i18n, ensure this is true

Prevention

Always create src/pages/index.astro when enabling prefixDefaultLocale.
If you don't want the auto-redirect, set prefixDefaultLocale to false.
Add an onboarding check in CI that asserts a '/' route exists when i18n is on.

When it happens

Trigger: Enabling i18n with prefixDefaultLocale: true (pathname-prefix-always) but having no src/pages/index.astro (or equivalent); the only index lives under a locale folder; index page was deleted.

Common situations: Setting up i18n for the first time without a root index page; restructuring pages into locale subfolders and removing the root index; i18n.defaultLocale pointing to a locale with no root index.

Related errors

AI-assisted analysis of withastro/astro@d081033d5f (2026-08-12). Data as JSON: /api/errors/c69995caabbc7f87. Report an issue: GitHub.