facebook/docusaurus · error · Error

Docusaurus bug, no locale config found for locale=${locale}

Error message

Docusaurus bug, no locale config found for locale=${locale}

What it means

Thrown by `LocaleDropdownNavbarItem` when `localeConfigs[locale]` is undefined for a requested locale. The message self-describes as a 'Docusaurus bug', signaling the team's intent that this should never happen for a properly-configured i18n setup — every locale in `i18n.locales` should have a corresponding config entry.

Source

Thrown at packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx:32

import IconLanguage from '@theme/Icon/Language';
import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
import type {Props} from '@theme/NavbarItem/LocaleDropdownNavbarItem';

import styles from './styles.module.css';

function useLocaleDropdownUtils() {
  const {
    siteConfig,
    i18n: {localeConfigs},
  } = useDocusaurusContext();
  const alternatePageUtils = useAlternatePageUtils();
  const search = useHistorySelector((history) => history.location.search);
  const hash = useHistorySelector((history) => history.location.hash);

  const getLocaleConfig = (locale: string) => {
    const localeConfig = localeConfigs[locale];
    if (!localeConfig) {
      throw new Error(
        `Docusaurus bug, no locale config found for locale=${locale}`,
      );
    }
    return localeConfig;
  };

  const getBaseURLForLocale = (locale: string) => {
    const localeConfig = getLocaleConfig(locale);
    const isSameDomain = localeConfig.url === siteConfig.url;
    if (isSameDomain) {
      // Shorter paths if localized sites are hosted on the same domain
      // This reduces HTML size a bit
      return `pathname://${alternatePageUtils.createUrl({
        locale,
        fullyQualified: false,
      })}`;
    }
    return alternatePageUtils.createUrl({

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Confirm every locale in `i18n.locales` resolves to an entry (Docusaurus auto-fills `localeConfigs`, so ensure no locale was orphaned).
2. Run `docusaurus clear` and rebuild so stale route/locale metadata is regenerated.
3. If you swizzled the dropdown, only iterate locales from `i18n.locales`, not from arbitrary URL parsing.
4. Report upstream if config is consistent and the invariant still breaks (the message explicitly invites a bug report).

Example fix

// before
i18n: { defaultLocale: 'en', locales: ['en', 'fr'], localeConfigs: { en: {...} } }
// fr has no config entry (should be auto-generated, but cache may be stale)
// after
i18n: { defaultLocale: 'en', locales: ['en', 'fr'], localeConfigs: { en: {...}, fr: {...} } }
// then run: docusaurus clear && docusaurus build

const {i18n} = useDocusaurusContext();
function localeIsConfigured(locale: string): boolean {
  return Object.prototype.hasOwnProperty.call(i18n.localeConfigs, locale);
}

function isConfiguredLocale(locale: string, localeConfigs: Record<string, unknown>): locale is string {
  return locale in localeConfigs;
}

When it happens

Trigger: The current route's locale (or a locale computed for the dropdown) is not present in `siteConfig.i18n.localeConfigs`. This can happen if the i18n config was altered, a locale was removed while routes still reference it, or an internal invariant between `i18n.locales` and `localeConfigs` was violated.

Common situations: Editing `i18n` config to drop a locale without clearing the build cache / generated routes; a deploy of a partially-synced config; a swizzled dropdown that synthesizes a locale string not declared in config; locale URL pathname parsing yielding an unexpected value.

Related errors

• DocSidebarNavbarItem: Sidebar with ID "${sidebarId}" doesn't
• No docs version exist for name '${name}', please verify your
• No NavbarItem component found for type "${type}".
• No tags file '${relativeFilePath}' could be found in any of
• Can't find locale config for locale ${logger.code(localeToLo

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/8a89a788dc37168a. Report an issue: GitHub.