The custom Next.js 404 page does not show for unknown URLs
Not-found page does not work in Next.js 13Short answer
In the App Router, not-found.js shows when notFound() is thrown in a segment, and the root app/not-found.js also handles URLs that match no route. If your page does not appear, the file is usually in the wrong folder, a page never calls notFound(), or the app has several root layouts and needs global-not-found.
Fix it fast
1Find out which cause you have
List where not-found files live. The one that catches unknown URLs must sit directly in the app folder.
find app src/app -name "not-found.*" 2>/dev/null2Match what you see, then jump to its fix
- 1
not-found.tsx exists only inside a nested folder such as app/blog/.The file is not in the root of the app directoryFix - 2
/blog/[slug] renders an empty page, or a null result, for an unknown slug.A dynamic page never calls notFound()Fix - 3
The app has app/(admin)/layout.tsx and app/(shop)/layout.tsx, or app/[country]/layout.tsx, and unknown URLs show the plain default page.Several root layouts, or a dynamic segment at the top, leave no layout for the 404Fix - 4
The not-found UI appears, yet the response status is 200 and search consoles report a soft 404.The page shows but the status code is 200Fix - 5
notFound() runs (a log line before it prints) but the page renders normally or shows your error handling.A try/catch swallows the notFound() callFix
- 1
What does the error look like?
Not-found page does not work in Next.js 13
Cause 1 of 5
The file is not in the root of the app directory
1Check
A not-found file in a segment is used only for notFound() thrown inside that segment. Since v13.3.0 the root app/not-found handles every URL that matches no route.
ls app/not-found.* app/layout.*2Fix
Create app/not-found.tsx with a default export. It takes no props.
// app/not-found.tsx
import Link from 'next/link'
export default function NotFound() {
return (
<div>
<h2>Not Found</h2>
<p>Could not find requested resource</p>
<Link href="/">Return Home</Link>
</div>
)
}3Verify
Open a URL that does not exist and see your own markup.
curl -i http://localhost:3000/no-such-pageConfirmed by nextjs.org
Cause 2 of 5
A dynamic page never calls notFound()
1Check
A route that matches a dynamic segment is a valid route. Next.js only shows not-found.js when the notFound function is thrown in it.
grep -rn "notFound" app/blog2Fix
Call notFound() from next/navigation when the data is missing.
// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'
export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params
const post = await getPost(slug)
if (!post) notFound()
return <h1>{post.title}</h1>
}3Verify
Request a slug that does not exist and check the status code.
curl -I http://localhost:3000/blog/does-not-existConfirmed by nextjs.org
Cause 3 of 5
Several root layouts, or a dynamic segment at the top, leave no layout for the 404
1Check
With no single layout to build a global 404 from, the docs point to global-not-found.js. It is experimental and was introduced in v15.4.0.
ls app/\(*\)/layout.* app/\[*\]/layout.* 2>/dev/null2Fix
Turn the flag on and add app/global-not-found.tsx. It must return a full HTML document and import its own styles and fonts, because it bypasses your layouts.
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: { globalNotFound: true },
}
export default nextConfig
// app/global-not-found.tsx
import './globals.css'
export default function GlobalNotFound() {
return (
<html lang="en">
<body>
<h1>404 - Page Not Found</h1>
</body>
</html>
)
}3Verify
Restart the dev server and open an unknown URL.
npm run devConfirmed by nextjs.org
Cause 4 of 5
The page shows but the status code is 200
1Check
Next.js returns 404 only before streaming starts. After streaming has started, the status stays 200 and the UI renders in the response.
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/blog/does-not-exist2Fix
If you need the 404 status, run the existence check before the response starts streaming: await the data in the page itself rather than inside a component wrapped in Suspense. If you keep the Suspense shell, accept the 200 status; Next.js still adds a noindex robots tag.
// app/blog/[slug]/page.tsx: check before any Suspense boundary
const post = await getPost(slug)
if (!post) notFound()3Verify
The curl command prints 404 for a missing slug.
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/blog/does-not-existConfirmed by nextjs.org
Cause 5 of 5
A try/catch swallows the notFound() call
1Check
notFound() works by throwing. A try/catch around it catches that exception and the not-found UI never renders. A call left in an un-awaited promise also renders nothing.
grep -rn -B3 -A3 "notFound()" app | grep -n "try\|catch"2Fix
Call notFound() outside the try block, or rethrow with unstable_rethrow first when you must catch errors near the call.
let user
try {
user = await fetchUser(id)
} catch (e) {
throw e
}
if (!user) notFound() // outside try/catch3Verify
Request an id that does not exist; the not-found UI appears.
curl -i http://localhost:3000/user/does-not-existConfirmed by nextjs.org
How do I stop it coming back?
- Put one app/not-found.tsx in the app root as soon as the project starts.
- Call notFound() in every dynamic route that loads data by id or slug.
- Keep the root not-found page a Server Component; the docs note it is sent with every route.
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
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb 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
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fix