{"record":{"id":"d5abca6eb252f296","repo":"withastro/astro","slug":"missinglocaleerror","errorCode":"MissingLocaleError","errorMessage":"The locale/path `${locale}` does not exist in the configured `i18n.locales`.","messagePattern":"The locale/path `(.+?)` does not exist in the configured `i18n\\.locales`\\.","errorType":"exception","errorClass":"AstroError","httpStatus":null,"severity":"error","filePath":"packages/astro/src/i18n/index.ts","lineNumber":69,"sourceCode":"\n/**\n * The base URL\n */\nexport function getLocaleRelativeUrl({\n\tlocale,\n\tbase,\n\tlocales: _locales,\n\ttrailingSlash,\n\tformat,\n\tpath,\n\tprependWith,\n\tnormalizeLocale = true,\n\tstrategy = 'pathname-prefix-other-locales',\n\tdefaultLocale,\n}: GetLocaleRelativeUrl) {\n\tconst codeToUse = peekCodePathToUse(_locales, locale);\n\tif (!codeToUse) {\n\t\tthrow new AstroError({\n\t\t\t...MissingLocale,\n\t\t\tmessage: MissingLocale.message(locale),\n\t\t});\n\t}\n\tconst pathsToJoin = [base, prependWith];\n\tconst normalizedLocale = normalizeLocale ? normalizeTheLocale(codeToUse) : codeToUse;\n\tif (\n\t\tstrategy === 'pathname-prefix-always' ||\n\t\tstrategy === 'pathname-prefix-always-no-redirect' ||\n\t\tstrategy === 'domains-prefix-always' ||\n\t\tstrategy === 'domains-prefix-always-no-redirect'\n\t) {\n\t\tpathsToJoin.push(normalizedLocale);\n\t} else if (locale !== defaultLocale) {\n\t\tpathsToJoin.push(normalizedLocale);\n\t}\n\tpathsToJoin.push(path);\n","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/withastro/astro/blob/d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca/packages/astro/src/i18n/index.ts#L51-L87","documentation":"`getLocaleRelativeUrl` (and related URL builders) look up the requested `locale` against the configured `i18n.locales` via `peekCodePathToUse`. If no configured locale's code/path matches the requested locale string, it throws `MissingLocaleError` because Astro cannot build a URL for a locale it was not told about.","triggerScenarios":"Calling `getLocaleRelativeUrl({ locale: 'fr', locales: config.locales, ... })` when `'fr'` is not present in the `locales` array passed in (neither as a bare string nor inside any locale object's `codes`).","commonSituations":"Typing or renaming a locale code that isn't in `astro.config` i18n.locales; passing a full language tag (e.g. `'pt-BR'`) when config only lists `'pt'`; mismatch between the locales array passed to the utility and the one in config; out-of-sync locale lists after editing config.","solutions":["Add the missing locale to `i18n.locales` in `astro.config.mjs`.","Pass exactly the `locales` value from your config to the utility instead of a hand-maintained copy.","If using locale objects with `codes`, ensure the requested code appears in that locale's `codes` array.","Guard the call with `pathHasLocale`/a code-membership check before invoking the URL builder."],"exampleFix":"// before\nconst url = getLocaleRelativeUrl({\n  locale: 'fr',\n  base, locales: config.locales, path: '/about',\n})\n// config has i18n.locales: ['en', 'es']  -> throws\n\n// after\n// astro.config.mjs: i18n: { locales: ['en', 'es', 'fr'] }\nconst url = getLocaleRelativeUrl({\n  locale: 'fr',\n  base, locales: config.locales, path: '/about',\n})","handlingStrategy":"type-guard","validationCode":"const configuredCodes = new Set(config.locales.flatMap(l => typeof l === 'string' ? [l] : l.codes));\nif (!configuredCodes.has(requestedLocale)) {\n  throw new Error(`Locale ${requestedLocale} not configured`);\n}","typeGuard":"function isConfiguredLocale(locale, locales) {\n  return locales.some(l =>\n    typeof l === 'string' ? l === locale : l.codes.includes(locale)\n  );\n}","tryCatchPattern":"null","preventionTips":["Always pass config.locales to i18n utilities rather than a hand-maintained list.","Validate requested locale codes against config before building URLs.","Use the exact locale strings declared in i18n.locales."],"tags":["i18n","config","routing","localization"],"backgroundTag":null,"analyzedSha":"d081033d5fe8e8a68c4bbbad4af9d2deb9c74bca","analyzedAt":"2026-08-12T13:37:29.035Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}