next-intl logs MISSING_MESSAGE and shows the key instead of text
MISSING_MESSAGEShort 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.
Fix it fast
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.json2Match what you see, then jump to its fix
- 1
The error names a locale (for example fr) that has fewer keys than the default localeThe key is missing in that locale's fileFix - 2
The error key has the right last word but the wrong prefixThe namespace path does not match the JSON nestingFix - 3
The key exists in the JSON, for example "one.two": "...", but is still reported missingA message key contains a dotFix - 4
Every key is missing, in every localeThe request config loads the wrong file or no messagesFix
- 1
What does the error look like?
MISSING_MESSAGEThe 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 devConfirmed by next-intl.dev
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.json2Fix
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.placeholder3Verify
The jq command above returns the string you expect, and the page shows it.
jq '.auth.SignUp.form.placeholder' messages/en.jsonConfirmed by next-intl.dev
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.json2Fix
Turn flat dotted keys into nested objects.
{ "one": { "two": "Text" } }3Verify
Look up the nested path with jq.
jq '.one.two' messages/en.jsonConfirmed by next-intl.dev
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/null2Fix
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 devConfirmed by next-intl.dev
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
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix