Next.js notFound() Error: This page could not be found

What causes this error

The notFound() function from next/navigation throws a special NEXT_NOT_FOUND error that Next.js catches internally to render the nearest not-found.tsx boundary. If no not-found.tsx file exists, Next.js falls back to a generic 404 page. Common issues: calling notFound() without creating a not-found.tsx file for a custom 404 UI, catch-all routes ([...slug]/page.tsx) matching URLs that should show a 404, the not-found.tsx file being placed in the wrong directory, or notFound() being called inside a try-catch block that accidentally swallows the error instead of letting it propagate to Next.js.

How to fix it

1. 01

   step 1

   Create the global not-found.tsx boundary

   Place a not-found.tsx file in the app/ directory root. This file renders whenever notFound() is called from any page or when no route matches the requested URL. It must export a default React component. It automatically returns a 404 HTTP status code.

   // app/not-found.tsx
   import Link from 'next/link';
   
   export const metadata = {
     title: 'Page Not Found',
   };
   
   export default function NotFound() {
     return (
       <main className="flex min-h-screen flex-col items-center justify-center">
         <h1 className="text-4xl font-bold">404</h1>
         <p className="mt-4 text-lg">This page could not be found.</p>
         <Link href="/" className="mt-6 underline">
           Return home
         </Link>
       </main>
     );
   }

   Copy
2. 02

   step 2

   Call notFound() correctly in data fetching

   Use notFound() from next/navigation in Server Components when a database query or API call returns no data. The function throws immediately — do not wrap it in a try-catch or it will not trigger the not-found.tsx boundary.

   // app/blog/[slug]/page.tsx
   import { notFound } from 'next/navigation';
   import { db } from '@/lib/db';
   
   export default async function BlogPost({
     params,
   }: {
     params: Promise<{ slug: string }>;
   }) {
     const { slug } = await params;
     const post = await db.post.findUnique({ where: { slug } });
   
     if (!post) {
       notFound(); // throws NEXT_NOT_FOUND — renders not-found.tsx
     }
   
     return <article><h1>{post.title}</h1></article>;
   }

   Copy
3. 03

   step 3

   Fix catch-all routes swallowing 404s

   A catch-all route ([...slug]/page.tsx) matches every URL under its segment, including paths that should return 404. You must validate the slug inside the catch-all and call notFound() for invalid paths. Optional catch-all ([[...slug]]) also matches the parent segment's index, which can cause additional conflicts.

   // app/docs/[...slug]/page.tsx
   import { notFound } from 'next/navigation';
   
   const validDocs = ['getting-started', 'api-reference', 'deployment'];
   
   export default async function DocsPage({
     params,
   }: {
     params: Promise<{ slug: string[] }>;
   }) {
     const { slug } = await params;
     const docPath = slug.join('/');
   
     // Validate the slug — don't let catch-all serve any random URL
     if (!validDocs.includes(docPath)) {
       notFound();
     }
   
     return <div>Doc: {docPath}</div>;
   }
   
   // Generate static params so only valid paths are pre-rendered
   export function generateStaticParams() {
     return validDocs.map((doc) => ({ slug: doc.split('/') }));
   }

   Copy
4. 04

   step 4

   Add segment-level not-found.tsx for nested layouts

   You can place not-found.tsx at any route segment level to customize the 404 UI for that section. A not-found.tsx inside app/dashboard/ renders within the dashboard layout when notFound() is called from any dashboard page.

   // app/dashboard/not-found.tsx — 404 within the dashboard layout
   import Link from 'next/link';
   
   export default function DashboardNotFound() {
     return (
       <div>
         <h2>Dashboard page not found</h2>
         <p>The section you requested does not exist.</p>
         <Link href="/dashboard">Back to dashboard</Link>
       </div>
     );
   }

   Copy

How to verify the fix

• Visiting a non-existent URL shows the custom 404 page with a 404 HTTP status code.
• Calling notFound() in a page renders the nearest not-found.tsx boundary.
• The browser's network tab shows a 404 status code, not a 200.
• Catch-all routes return 404 for invalid slugs instead of rendering empty or broken pages.