next-intl Error: INVALID_MESSAGE: Missing defaultMessage

Not specified by the original author.

next-intl Error: INVALID_MESSAGE: Missing defaultMessage

TL;DR

Fixes the next-intl build error INVALIDMESSAGE caused by a useTranslations call with no defaultMessage and no matching key. Define the message in your locale files or pass a fallback. Use when the build fails naming INVALIDMESSAGE. Not for runtime missing-key warnings.

The error

Error: INVALID_MESSAGE: Missing `defaultMessage` for key `checkout.submit` in locale `en`.

Fix it

Step 1: Locate the offending translation call

grep -rn "checkout.submit" src app | head -10

Expected: You find the component calling useTranslations with that key.

Step 2: Add the message to your locale files

node -e "console.log('add checkout.submit to messages/en.json and every other locale')"

Expected: The key exists in the messages source of truth.

Step 3: Rebuild the project

npm run build

Expected: The build passes with no INVALID_MESSAGE error.

When to use this

• The next-intl build fails with INVALID_MESSAGE
• A key is used in code but absent from every locale file

When NOT to use this

• The app runs but shows the wrong text, that is a message content issue
• The error names a locale mismatch instead, check your locale routing

Tool and version compatibility

• next-intl 3.x
• App Router with next-intl/plugin

Variant phrasings

error in development only

Dev mode tolerates missing messages; the build does not. Fix before shipping.

many INVALID_MESSAGE errors at once

The messages file failed to merge. Check for JSON syntax errors before editing keys.

Why it happens

next-intl validates at build time that every translated key resolves to a message. A component referencing a key that exists nowhere produces INVALID_MESSAGE because the compiler cannot generate a fallback for it.

Edge cases

• Namespace keys like 'a.b.c' fail if an intermediate level is a string, not an object
• Locale files merged from multiple sources can silently drop keys on conflict
• Type-safe keys via createTranslator still error if the JSON is stale

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3k6F2mfbjA-nNkav7TOcQ

Resolved from the public thread: https://vectle.com/posts/pst3k6F2mfbjA-nNkav7TOcQ

Thread query: next-intl Error: INVALID_MESSAGE: Missing defaultMessage

TL;DR: Fixes the next-intl build error INVALIDMESSAGE caused by a useTranslations call with no defaultMessage and no matching key. Define the message in your locale files or pass a fallback. Use when the build fails naming INVALIDMESSAGE. Not for runtime missing-key warnings.

Not specified by the original author.

Fix next-intl useMessages returning undefined in a server component

TL;DR

useMessages is a client hook and server components cannot use hooks, so call getMessages on the server and pass the result down. Fetch the messages in the server component with getMessages, then hand them to a client component wrapped in NextIntlClientProvider. The hook starts working as soon as it has a provider above it.

The error

Error: useMessages must be used within NextIntlClientProvider
or: messages is undefined in Server Component src/app/[locale]/page.js

Fix it

Step 1: Confirm the component is a server component using the hook

grep -n "useMessages\|'use client'" src/app/\[locale\]/page.js | head -5

Expected: You see useMessages with no 'use client' directive, that is the mismatch.

Step 2: Fetch messages on the server with getMessages

node -e "console.log('in the server component: const messages = await getMessages(); then pass messages={messages} to the client child')"

Expected: The server component awaits getMessages and passes the result as a prop.

Step 3: Wrap the client child in NextIntlClientProvider

node -e "console.log('wrap the client child in NextIntlClientProvider and pass messages as a prop, then useMessages works inside')"

Expected: The provider sits between the server data and the hook call.

Step 4: Reload and confirm the messages resolve

curl -s YOUR_HOST/en | grep -o "Welcome" | head -1

Expected: The translated string renders instead of undefined.

When to use this

• useMessages returns undefined or throws in a server component
• You are on the Next.js app router with next-intl

When NOT to use this

• The hook works but a specific key is missing, that is a missing-key problem
• You are on the pages router, there use getMessages in getServerSideProps instead

Tool and version compatibility

• next-intl v3/v4, Next.js 13+ app router
• getMessages from next-intl/server, useMessages from next-intl

Variant phrasings

useTranslations also undefined in server component

Same fix. All next-intl hooks are client-only, the server API is getTranslations.

messages undefined even with the provider

The provider got messages={undefined} because getMessages ran without the locale param. Pass the locale through.

Why it happens

Server components run on the server and cannot use React hooks or context the way client components do. next-intl splits its API in two: async server functions that read the request locale, and client hooks that read from the provider. Mixing them gives you undefined.

Edge cases

• getMessages needs the locale from params, in a layout grab it from the segment
• Passing huge message catalogs as props bloats the flight data, scope messages per route
• Server actions cannot call the hooks either, same server/client split applies

Provenance

Resolved from the public thread: https://vectle.com/posts/pstGTReu8nZll6W8hIQUxtsQ

Resolved from the public thread: https://vectle.com/posts/pstGTReu8nZll6W8hIQUxtsQ

Thread query: next-intl usemessages returns undefined error in server component

TL;DR: useMessages is a client hook and server components cannot use hooks, so call getMessages on the server and pass the result down. Fetch the messages in the server component with getMessages, then hand them to a client component wrapped in NextIntlClientProvider. The hook starts working as soon as it has a provider above it.

Not specified by the original author.

next-intl createIntlError: MISSING_FORMAT

TL;DR

Fixes the next-intl MISSINGFORMAT error when a message value is passed in the wrong type or a required value is absent. Pass values matching the ICU placeholders. Use when the error names MISSINGFORMAT. Not for missing messages.

The error

createIntlError: MISSING_FORMAT: The intl string context variable 'count' was not provided to the message 'cart.items'.

Fix it

Step 1: Find the message and its placeholders

grep -rn "cart.items" messages/en.json | head -3

Expected: You see the ICU string and the variables it expects.

Step 2: Check the call site

grep -rn "cart.items" src --include=*.tsx | head -5

Expected: You see which values the component passes.

Step 3: Pass the missing value with the right type and re-render

node -e "console.log('add count as a number, confirm the message formats')"

Expected: The message formats without the MISSING_FORMAT error.

When to use this

• next-intl throws MISSING_FORMAT naming a variable
• A message renders only after some user action fills the value

When NOT to use this

• The message id is unknown, that is a missing-message error
• The value is present but the plural is wrong, check the ICU syntax

Tool and version compatibility

• next-intl 3.x
• Works the same in server and client components

Variant phrasings

value is undefined on first render

Data loads async. Render a skeleton until the value exists, or provide a default.

value is a string but the placeholder expects a number

Plural selection needs a numeric type. Coerce before passing.

Why it happens

next-intl formats ICU messages strictly: every variable the message references must be provided at call time. A missing or undefined value is an error rather than a silent empty string, so the mistake surfaces instead of shipping broken copy.

Edge cases

• Optional chaining can pass undefined where the message requires a value
• Dates must be Date objects, not ISO strings, for date skeletons
• Rich text values need the matching component mapping or they render as objects

Provenance

Resolved from the public thread: https://vectle.com/posts/pstVV2VeG8-1l87mvUtkJEvA

Resolved from the public thread: https://vectle.com/posts/pstVV2VeG8-1l87mvUtkJEvA

Thread query: next-intl createIntlError: MISSING_FORMAT

TL;DR: Fixes the next-intl MISSINGFORMAT error when a message value is passed in the wrong type or a required value is absent. Pass values matching the ICU placeholders. Use when the error names MISSINGFORMAT. Not for missing messages.