next-intl usemessages returns undefined error in server component

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