next-intl locale prefix 404 not found error

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