withastro/astro · error · AstroError

i18nNoLocaleFoundInPath

i18nNoLocaleFoundInPath

Error message

You tried to use an i18n utility on a path that doesn't contain any locale. You can use `pathHasLocale` first to determine if the path has a locale.

What it means

getPathByLocale() maps a locale code to its configured path: it scans `i18n.locales` for a string entry equal to the code, or an object entry whose `codes` array contains it, and returns the corresponding path. If no configured locale matches the given code, it throws i18nNoLocaleFoundInPath.

Solutions

1. Add the code to i18n.locales (as a string entry or inside an object's codes array).
2. Pass a code that exactly matches a configured entry, including case.
3. Validate the code against getAllCodes(locales) or your own list before calling getPathByLocale.

Example fix

// before
const path = getPathByLocale('fr', [{ path: 'english', codes: ['en'] }]); // throws

// after
const path = getPathByLocale('en', [{ path: 'english', codes: ['en'] }]); // 'english'

import { getAllCodes } from 'astro:i18n';
// before getPathByLocale(code, locales)
const known = new Set(getAllCodes(locales));
if (!known.has(code)) {
  // fall back to the default locale instead of throwing
  code = defaultLocale;
}

function isConfiguredCode(code: string, locales: Locales): boolean {
  return locales.some((l) =>
    typeof l === 'string' ? l === code : l.codes.includes(code),
  );
}

When it happens

Trigger: Calling getPathByLocale('fr', locales) when no locale 'fr' is configured as a string entry or inside any codes array; a misspelled or differently-cased locale code reaching i18n routing internals; locales list loaded from a different source than the one used to validate the code.

Common situations: Locale codes coming from content frontmatter, headers (Accept-Language), or a CMS that are broader than i18n.locales; editing i18n.locales without updating callers that pass hardcoded codes; case mismatches between configured codes and lookup values.

Related errors

• MissingIndexForInternationalizationError
• MissingLocaleError
• i18nNotEnabled
• IncorrectStrategyForI18n
• InvalidI18nMiddlewareConfiguration

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

Appendix: source

Thrown at packages/astro/src/i18n/index.ts:180

 * Given a locale (code), it returns its corresponding path
 * @param locale
 * @param locales
 */
export function getPathByLocale(locale: string, locales: Locales): string {
	for (const loopLocale of locales) {
		if (typeof loopLocale === 'string') {
			if (loopLocale === locale) {
				return loopLocale;
			}
		} else {
			for (const code of loopLocale.codes) {
				if (code === locale) {
					return loopLocale.path;
				}
			}
		}
	}
	throw new AstroError(i18nNoLocaleFoundInPath);
}

/**
 * A utility function that retrieves the preferred locale that correspond to a path.
 *
 * @param path
 * @param locales
 */
export function getLocaleByPath(path: string, locales: Locales): string {
	for (const locale of locales) {
		if (typeof locale !== 'string') {
			if (locale.path === path) {
				// the first code is the one that user usually wants
				const code = locale.codes.at(0);
				if (code === undefined) throw new AstroError(i18nNoLocaleFoundInPath);
				return code;
			}
		} else if (locale === path) {

View on GitHub (pinned to 52e6c34790)