Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

next-intl logs MISSING_MESSAGE and shows the key instead of text

ErrorMISSING_MESSAGE

Short answer

MISSING_MESSAGE means next-intl asked for a key it cannot find in the messages it was given. The page then shows namespace.key instead of text. Check that the key exists in the active locale file, that the namespace path matches the nesting, that no key contains a dot, and that messages actually reach the component.

  • Applies to next-intl 4, Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask next-intl which messages exist for the locale. The simplest way is to open the JSON file for the locale in the error and search for the key.

    grep -n "title" messages/en.json
  2. 2Match what you see, then jump to its fix

    1. 1The error names a locale (for example fr) that has fewer keys than the default localeThe key is missing in that locale's fileFix
    2. 2The error key has the right last word but the wrong prefixThe namespace path does not match the JSON nestingFix
    3. 3The key exists in the JSON, for example "one.two": "...", but is still reported missingA message key contains a dotFix
    4. 4Every key is missing, in every localeThe request config loads the wrong file or no messagesFix

What does the error look like?

  • MISSING_MESSAGE
  • The page shows Home.title instead of the translated text

Cause 1 of 4

The key is missing in that locale's file

1Check

Messages are plain JSON files, one per locale. A key added to en.json but not to the other files is missing there. By default next-intl logs the error and renders namespace.key to keep the app running.

diff <(jq -S 'paths|join(".")' messages/en.json) <(jq -S 'paths|join(".")' messages/fr.json)

2Fix

Add the missing key to the file. If incomplete translations are expected, handle that case in onError so a missing message only logs, and use t.has to test before reading.

// i18n/request.ts
onError(error) {
  if (error.code === IntlErrorCode.MISSING_MESSAGE) {
    console.error(error.message); // expected for incomplete locales
  } else {
    throw error;
  }
},

3Verify

Reload the page in that locale; the translated text appears and the log is quiet.

npm run dev

Confirmed by next-intl.dev

Did this fix it?

Cause 2 of 4

The namespace path does not match the JSON nesting

1Check

A namespace can be a path such as useTranslations('auth.SignUp'), and the rest is resolved with dots, as in t('form.placeholder'). If the JSON is nested differently, the lookup misses.

jq '.auth.SignUp.form' messages/en.json

2Fix

Make the namespace passed to useTranslations plus the key passed to t equal the real path in the JSON.

const t = useTranslations('auth.SignUp');
t('form.placeholder'); // reads auth.SignUp.form.placeholder

3Verify

The jq command above returns the string you expect, and the page shows it.

jq '.auth.SignUp.form.placeholder' messages/en.json

Confirmed by next-intl.dev

Did this fix it?

Cause 3 of 4

A message key contains a dot

1Check

The docs say keys cannot contain the character . because it expresses nesting. A flat key like 'one.two' is read as one then two.

grep -n -E '^\s*"[^"]*\.[^"]*":' messages/en.json

2Fix

Turn flat dotted keys into nested objects.

{ "one": { "two": "Text" } }

3Verify

Look up the nested path with jq.

jq '.one.two' messages/en.json

Confirmed by next-intl.dev

Did this fix it?

Cause 4 of 4

The request config loads the wrong file or no messages

1Check

Messages come from the async function in i18n/request.ts, for example a dynamic import of the locale's JSON file. A wrong relative path or an unresolved locale gives an empty set. Client Components also receive messages only through NextIntlClientProvider; passing messages={null} sends none.

cat i18n/request.ts; grep -rn "NextIntlClientProvider" app src 2>/dev/null

2Fix

Import the file for the resolved locale with the correct relative path, and do not pass messages={null} to the provider for components that need them.

return {
  locale,
  messages: (await import(`../../messages/${locale}.json`)).default
};

3Verify

Restart the dev server and load a page in each locale.

npm run dev

Confirmed by next-intl.dev

Did this fix it?

How do I stop it coming back?

  • Run a small script in CI that compares the key list of every locale file with the default locale.
  • Keep keys nested and dot-free from the start.
  • Define onError so missing messages are logged once, with the locale, instead of drowning other errors.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.