next-intl locale prefix 404 not found error

Not specified by the original author.

Fix next-intl locale prefix 404 not found

TL;DR

Your middleware matcher or localePrefix setting does not cover the URL being requested, so align them. Check what the middleware actually matches against the URL that 404s. The classic cause is the matcher skipping the prefixed path, or localePrefix set to as-needed while links still include the prefix.

The error

404: This page could not be found
GET /en/about to 404, while /about renders fine without a prefix

Fix it

Step 1: Look at the URL that 404s and your middleware matcher

grep -n "matcher" src/middleware.js; grep -n "localePrefix" src/i18n/routing.js

Expected: You see the matcher pattern and the localePrefix mode side by side.

Step 2: Make the matcher cover prefixed paths

node -e "console.log('matcher should skip api, _next, and static files so /en/about reaches the middleware')"

Expected: The matcher pattern matches /en/about.

Step 3: Set localePrefix consistently with your links

node -e "console.log('always: every URL has /en, as-needed: default locale has no prefix, never: no prefixes at all')"

Expected: The setting matches how your Link components build URLs.

Step 4: Reload the prefixed URL

curl -s -o /dev/null -w "%{http_code}" YOUR_HOST/en/about

Expected: You get 200 instead of 404.

When to use this

• Prefixed URLs like /en/about 404 in a next-intl app
• You changed localePrefix mode and routes broke

When NOT to use this

• Unprefixed URLs 404 too, that is a missing page not a locale issue
• The page renders but in the wrong language, check locale detection

Tool and version compatibility

• next-intl v3/v4, Next.js 13+ app router with middleware
• localePrefix modes: always, as-needed, never

Variant phrasings

404 only for the default locale prefix

You use as-needed, so /en/about correctly 404s while /about works. Either link without the prefix or switch to always.

404 after deploying to a subpath

Add the basePath to the matcher and the routing config, the middleware sees the full path.

Why it happens

next-intl routing is two parts that must agree: the middleware rewrites or redirects prefixed URLs, and the localePrefix setting decides which URLs are valid. When they disagree, Next.js finds no matching route and returns 404.

Edge cases

• Static export does not run middleware, prefixed routes need explicit generateStaticParams
• Rewrites in next.config can fight the middleware, check both
• Trailing-slash settings change which URL the middleware sees, keep them consistent

Provenance

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

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

Thread query: next-intl locale prefix 404 not found error

TL;DR: Your middleware matcher or localePrefix setting does not cover the URL being requested, so align them. Check what the middleware actually matches against the URL that 404s. The classic cause is the matcher skipping the prefixed path, or localePrefix set to as-needed while links still include the prefix.

Not specified by the original author.

Fix next-intl middleware locale detection redirect loop

TL;DR

The middleware keeps redirecting because the locale it detects never sticks, so stop the loop by excluding the redirect target from detection. Usually the matcher re-runs on the already-prefixed URL, or the cookie and the Accept-Language header disagree forever. Make detection idempotent: if the URL already has a valid prefix, do nothing.

The error

ERR_TOO_MANY_REDIRECTS on YOUR_HOST/
/ to /en to /en to /en ... (network tab shows the same redirect repeating)

Fix it

Step 1: Watch the redirect chain to see the loop

curl -s -o /dev/null -w "%{redirect_url}" YOUR_HOST/ | head -c 200

Expected: You see the URL redirecting to itself or bouncing between two URLs.

Step 2: Check the middleware matcher for self-matching

grep -n "matcher" -A 3 src/middleware.js

Expected: The matcher must not re-trigger on URLs that already carry a locale prefix.

Step 3: Make detection skip already-prefixed paths

node -e "console.log('pattern: if the pathname starts with a known locale, return NextResponse.next() with no redirect')"

Expected: One request, one redirect at most, then the prefixed page serves.

Step 4: Clear the locale cookie and retry

curl -s -c /tmp/cj -b /tmp/cj -o /dev/null -w "%{http_code} %{redirect_url}" YOUR_HOST/

Expected: You get a single 307 to /en and then a 200.

When to use this

• The browser reports too many redirects on a next-intl site
• The network tab shows / bouncing to /en repeatedly

When NOT to use this

• A single redirect to the wrong locale, that is a detection config issue not a loop
• Redirects involving auth pages, check your auth middleware order

Tool and version compatibility

• next-intl v3/v4 middleware, Next.js 12/13/14
• Locale detection via Accept-Language header, cookie, or both

Variant phrasings

loop between /en and /en-US

Your locales list has both but detection canonicalizes differently than the prefix. Pick one form and stick to it.

loop only for logged-in users

Something sets the locale cookie after the middleware runs. Set it before, or let the middleware own it.

Why it happens

The middleware redirects to add the locale prefix, but on the next request it runs again and redirects again, because the already-prefixed URL still looks undetected to it, or the cookie it sets gets overwritten. Each pass looks like a fresh visitor, so it never stops.

Edge cases

• Multiple middleware in a chain can each redirect, merge them into one response
• Domain-based routing plus prefix routing double up, use one strategy
• Bots without Accept-Language can loop forever, give them the default locale with no redirect

Provenance

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

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

Thread query: next-intl middleware locale detection redirect loop error

TL;DR: The middleware keeps redirecting because the locale it detects never sticks, so stop the loop by excluding the redirect target from detection. Usually the matcher re-runs on the already-prefixed URL, or the cookie and the Accept-Language header disagree forever. Make detection idempotent: if the URL already has a valid prefix, do nothing.

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.