Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

The custom Next.js 404 page does not show for unknown URLs

ErrorNot-found page does not work in Next.js 13

Short 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.

  • Applies to Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1not-found.tsx exists only inside a nested folder such as app/blog/.The file is not in the root of the app directoryFix
    2. 2/blog/[slug] renders an empty page, or a null result, for an unknown slug.A dynamic page never calls notFound()Fix
    3. 3The 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. 4The 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. 5notFound() runs (a log line before it prints) but the page renders normally or shows your error handling.A try/catch swallows the notFound() callFix

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-page

Confirmed by nextjs.org

Did this fix it?

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/blog

2Fix

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-exist

Confirmed by nextjs.org

Did this fix it?

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/null

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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-exist

2Fix

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-exist

Confirmed by nextjs.org

Did this fix it?

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/catch

3Verify

Request an id that does not exist; the not-found UI appears.

curl -i http://localhost:3000/user/does-not-exist

Confirmed by nextjs.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.