Next.js not-found.tsx and notFound() Guide

Published: October 8, 2026 · 8 min read

Create app/not-found.tsx for the 404 page. Call notFound() from next/navigation when data is missing. Next.js then renders that file.

How does not-found.tsx work?

Open a URL that does not exist and Next.js shows a plain screen with "404" and "This page could not be found." A not-found.tsx file directly under app replaces that screen with your own design.

not-found.tsx is a special file name. The .js and .tsx extensions work the same way. It is a Server Component, it renders inside the root layout (app/layout.tsx), and your header and footer come along. The component accepts no props.

Since Next.js 13.3, the root app/not-found.tsx has two jobs. It renders when notFound() bubbles to the top of the tree, and it handles any URL that matches no route. A not-found.tsx inside a folder runs only when notFound() is called in that segment.

The samples in this guide target Next.js 15. This site depends on next 15.5 (the ^15.5.27 range in package.json).

app/not-found.tsx
import Link from "next/link";

export default function NotFound() {
  return (
    <main className="mx-auto flex min-h-[70vh] max-w-xl flex-col items-center justify-center px-6 py-24 text-center">
      <p className="text-sm font-semibold tracking-widest text-zinc-500">404</p>
      <h1 className="mt-3 text-3xl font-semibold text-zinc-900">Page not found</h1>
      <p className="mt-4 text-zinc-600">
        The URL may have changed, or the page may have been removed.
      </p>
      <Link
        href="/"
        className="mt-8 inline-flex min-h-11 items-center rounded-full bg-zinc-900 px-6 text-sm font-medium text-white hover:bg-zinc-700"
      >
        Back to home
      </Link>
    </main>
  );
}

Set metadata on the root not-found.tsx

The root app/not-found.tsx can export metadata or generateMetadata. A tab title of "Page not found" tells the visitor what happened.

The file-convention docs name metadata support for that root file and for global-not-found.tsx, covered below.

app/not-found.tsx (add at the top)
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Page not found",
};

global-not-found.tsx is experimental in Next.js 15.4 and later

Next.js 15.4.0 added an experimental app/global-not-found.tsx. The current file-convention docs still mark it experimental. Turn it on with experimental.globalNotFound: true in next.config.

It answers URLs that match no route, skips your root layout, and must return a full document with html and body. Import the styles and fonts this page needs inside the file.

Reach for it when you have more than one root layout, or when the root layout is a dynamic segment such as app/[locale]/layout.tsx. Otherwise app/not-found.tsx is enough. On this site's Next.js 15.5 it stays off until you set the flag.

next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    globalNotFound: true,
  },
};

export default nextConfig;

When should I call notFound()?

A route like app/blog/[slug]/page.tsx matches any string, including a post that does not exist. Call notFound() from next/navigation when the data is missing. Rendering of that segment stops, and the nearest not-found.tsx takes over.

Call it from a Server Component, a Server Function, or a Route Handler. You can also call it inside generateMetadata. The generateMetadata docs list notFound() next to redirect().

notFound() throws. You do not return it. Its return type is never, so TypeScript treats post as defined after the check. A try/catch around the call swallows the 404 UI. A call left in a promise the component does not await never renders the not-found screen, and in development the server logs an unhandled rejection.

app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { cache } from "react";
import { getPostBySlug } from "@/lib/posts"; // returns undefined when the post does not exist

// Share one fetch between generateMetadata and the page
const getPost = cache(getPostBySlug);

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();
  return { title: post.title, description: post.excerpt };
}

export default async function BlogPostPage({ params }: Props) {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) notFound();

  return (
    <article className="mx-auto max-w-2xl px-6 py-24">
      <h1 className="text-3xl font-semibold">{post.title}</h1>
      <div className="mt-8 leading-relaxed text-zinc-700">{post.body}</div>
    </article>
  );
}

Key points of the notFound() code

  • In Next.js 15, params is a Promise, so await it before reading slug. Next.js 14 passed a plain object

  • Nothing after notFound() runs

  • The same call inside generateMetadata keeps a missing post from publishing a normal title

  • Wrapping the fetcher in React's cache means the title and the body share a single fetch. fetch itself is already memoized by Next.js

How do I make a 404 for one route segment?

You can place not-found.tsx in any folder. With app/blog/not-found.tsx, a notFound() call inside the blog uses that file. The closest file wins, so the screen can link back to the post list instead of the home page.

That file does not catch every unknown URL on the site. Unmatched URLs are handled by the root app/not-found.tsx (since Next.js 13.3). If you turn on the experimental global-not-found.tsx from 15.4, unmatched URLs go there instead.

app/blog/not-found.tsx
import Link from "next/link";

export default function BlogNotFound() {
  return (
    <main className="mx-auto max-w-xl px-6 py-24 text-center">
      <h1 className="text-2xl font-semibold text-zinc-900">Post not found</h1>
      <p className="mt-4 text-zinc-600">The post URL may have changed, or it is no longer published.</p>
      <Link
        href="/blog"
        className="mt-8 inline-flex min-h-11 items-center rounded-full bg-zinc-900 px-6 text-sm font-medium text-white"
      >
        All posts
      </Link>
    </main>
  );
}

404 pages on multilingual sites with [locale]

Sites with the language at the start of the URL put their pages under app/[locale]. app/[locale]/not-found.tsx renders when notFound() is called inside that segment. It is not used for URLs that match no route.

Add a catch-all page that receives every remaining URL and calls notFound(). Libraries such as next-intl document this approach. not-found.tsx accepts no props, so pick the display language the way your i18n library recommends.

If the only root layout is [locale], the experimental global-not-found.tsx from Next.js 15.4 is another option. It uses the same flag as the section above.

app/[locale]/[...rest]/page.tsx
import { notFound } from "next/navigation";

// Catch every unmatched URL here and render the [locale] not-found.tsx
export default function CatchAllPage() {
  notFound();
}

Does not-found.tsx return a 404 status?

Before the response starts streaming, Next.js returns HTTP 404. After streaming has started, the status stays 200 and the not-found UI still renders. Next.js injects a noindex tag in both cases, so you do not add a robots meta tag yourself.

Streaming usually starts because a loading.tsx in that segment shows a fallback first, or because the missing-data check sits inside Suspense. The segment's not-found UI renders between that loading boundary and the page.

On a production build, check the status with curl -I https://example.com/no-such-page. A 200 does not always mean the file is in the wrong place. Once the shell has started streaming, the status stays 200, and the noindex tag is what keeps the URL out of search results.

Decide what goes on your 404 page

A 404 page exists to send lost visitors somewhere useful. Before any fancy effect, get these three in place:

  • A short heading that says what happened ("Page not found")

  • A button back to the home page

  • Site search, or links to your most-read pages

A search form that submits with GET works in a Server Component. Point /search at your own search page.

Those pieces also cover why the page is worth building: a way back to home or a popular page, a header and colors that still look like your site, and a real 404 so dead URLs are less likely to stay in search results.

app/not-found.tsx (with content added)
import Link from "next/link";

const popular = [
  { href: "/blog", label: "All blog posts" },
  { href: "/pricing", label: "Pricing" },
  { href: "/contact", label: "Contact" },
];

export default function NotFound() {
  return (
    <main className="mx-auto max-w-xl px-6 py-24 text-center">
      <p className="text-sm font-semibold tracking-widest text-zinc-500">404</p>
      <h1 className="mt-3 text-3xl font-semibold text-zinc-900">Page not found</h1>
      <p className="mt-4 text-zinc-600">The URL may have changed, or the page may have been removed.</p>

      <form action="/search" method="get" role="search" className="mt-8 flex gap-2">
        <label htmlFor="q" className="sr-only">Search this site</label>
        <input
          id="q"
          name="q"
          type="search"
          placeholder="Search by keyword"
          className="min-h-11 flex-1 rounded-full border border-zinc-300 px-4 text-base"
        />
        <button type="submit" className="min-h-11 rounded-full bg-zinc-900 px-5 text-sm font-medium text-white">
          Search
        </button>
      </form>

      <ul className="mt-10 space-y-1 text-sm">
        {popular.map((item) => (
          <li key={item.href}>
            <Link href={item.href} className="inline-flex min-h-11 items-center underline underline-offset-4">
              {item.label}
            </Link>
          </li>
        ))}
      </ul>

      <Link
        href="/"
        className="mt-8 inline-flex min-h-11 items-center rounded-full border border-zinc-300 px-6 text-sm font-medium"
      >
        Back to home
      </Link>
    </main>
  );
}

Write 404 page copy that does not blame the reader

"You typed the wrong URL" sounds like the visitor's fault, yet broken links often come from the site itself. Stick to the facts: "not found", "may have moved".

If you add an illustration or a joke, keep the way back visible without scrolling.

Add a subtle animation to the 404 page

Letting a big 404 numeral float up into place is enough to change the feel. Run it once and keep it around half a second.

Use Motion (formerly Framer Motion). Put only the animated part in its own file, add "use client" at the top, and leave not-found.tsx as a Server Component.

components/NotFoundNumber.tsx
"use client";

import { motion, useReducedMotion } from "motion/react";

export function NotFoundNumber() {
  const reduceMotion = useReducedMotion();

  return (
    <motion.p
      aria-hidden="true"
      initial={reduceMotion ? false : { opacity: 0, y: 24 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.6, ease: "easeOut" }}
      className="text-[8rem] font-semibold leading-none tracking-tight text-zinc-900 sm:text-[12rem]"
    >
      404
    </motion.p>
  );
}

Key points of the 404 page animation

  • For people who prefer reduced motion, initial is false, so the numeral is simply shown

  • The big numeral is decoration, so it gets aria-hidden and the h1 does the talking

  • Do not delay the link back until the motion finishes

Motion basics are covered in https://design-layer.com/en/articles/nextjs-framer-motion-guide.

Common 404 page mistakes and pre-launch checks

  • Returning an empty page when data is missing. Without notFound(), a blank page reaches search engines as a 200

  • Auto-redirecting from the 404 page to home. Visitors lose track of what happened, and the missing page is not signaled clearly

  • No link back, or one buried at the bottom

  • Adding "use client" to the whole 404 page. Split out only the animated part

  • Returning 404 for pages that merely moved. If there is a new location, redirect with redirects in next.config

  • Wrapping notFound() in try/catch. Once the throw is swallowed, the 404 UI does not render

Before launch, open a URL that does not exist and check the result on a production build (next build).

Copy a finished 404 page instead

The Statue 404 page on DesignLayer: check the live preview on the left, then copy the source with Copy for Cursor on the right
The Statue 404 page on DesignLayer: check the live preview on the left, then copy the source with Copy for Cursor on the right

The steps above give you a working 404 page. A paper texture, a statue in the center, and colors matched to the site take longer to build by hand.

When you want that layout already built, drop Statue 404 into not-found.tsx. It is an editorial error page: a giant wordmark on textured paper with a marble statue cut-out in the center. Swap the copy, the statue image, and the accent color.

Press Copy for Cursor on the detail page to copy the integration instructions, the live preview URL, the component TSX, and npm dependencies in one go. Browsing and live previews are free with no account or card, and free source copies are Components are free to copy, plus 1 video prompt a month. Blocks, Templates, and MCP are the 30-Day Build Pass ($19 once), Lifetime Access ($79 once), or Plus ($9/month).

Next.js 404 page: common questions

  • not-found.tsx is the UI file. notFound() is the function from next/navigation that triggers it. Putting the file in place does not by itself 404 a dynamic route whose data is missing.

Summary: building a 404 page in Next.js

  • Put not-found.tsx directly under app. It covers unmatched URLs and notFound() calls that bubble to the root

  • Call notFound() on a dynamic route when the data is missing. Do not return it

  • A not-found.tsx inside a folder runs only for notFound() in that segment

  • The status is 404 before streaming and 200 after. noindex is added either way

  • On [locale] sites, call notFound() from a catch-all page for the remaining URLs

Start by adding not-found.tsx under app and opening a URL that does not exist.

The screen people see while data loads is covered in https://design-layer.com/en/articles/nextjs-loading-screen-guide.

Components in this guide

Browse components →

Related guides