not-found.js

Next.js provides two conventions to handle not found cases:

not-found.js: Used when you call the notFound function in a route segment.
global-not-found.js: Used to define a global 404 page for unmatched routes across your entire app. This is handled at the routing level and doesn't depend on rendering a layout or page.

`not-found.js`

The not-found file is used to render UI when the notFound function is thrown within a route segment. Along with serving a custom UI, Next.js will return a 200 HTTP status code for streamed responses, and 404 for non-streamed responses (see Status Codes for details about SEO).

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>
  )
}

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>
  )
}

In the component hierarchy, not-found.js renders between loading.js and page.js. It is wrapped by the <Suspense> boundary from loading.js and the error boundary from error.js in the same segment.

Good to know: The default not found UI follows the operating system's color scheme via prefers-color-scheme and does not read an app-level theme (such as a class or data-theme attribute on <html>). Because it renders inside your root layout, the quickest way to match an explicit theme is to add a higher-specificity rule pair in your global stylesheet, scoped to your theme selector — for example html[data-theme='light'] body and html[data-theme='dark'] body. For full control over the markup, provide your own not-found.js.

`global-not-found.js` (experimental)

The global-not-found.js file lets you define a 404 page for your entire application. Unlike not-found.js, which works at the route level, this is used when a requested URL doesn't match any route at all. Next.js skips rendering and directly returns this global page.

The global-not-found.js file bypasses your app's normal rendering, which means you'll need to import any global styles, fonts, or other dependencies that your 404 page requires. This includes your theme: because global-not-found.js bypasses your layout, the OS color scheme is the only signal the default UI sees, so apply your theme (class or attribute) inside this file.

Good to know: A smaller version of your global styles, and a simpler font family could improve performance of this page.

global-not-found.js is useful when you can't build a 404 page using a combination of layout.js and not-found.js. This can happen in two cases:

Your app has multiple root layouts (e.g. app/(admin)/layout.tsx and app/(shop)/layout.tsx), so there's no single layout to compose a global 404 from.
Your root layout is defined using top-level dynamic segments (e.g. app/[country]/layout.tsx), which makes composing a consistent 404 page harder.

To enable it, add the globalNotFound flag in next.config.ts:

import type { NextConfig } from 'next'

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

export default nextConfig

Then, create a file in the root of the app directory: app/global-not-found.js:

// Import global styles and fonts
import './globals.css'
import { Inter } from 'next/font/google'
import type { Metadata } from 'next'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: '404 - Page Not Found',
  description: 'The page you are looking for does not exist.',
}

export default function GlobalNotFound() {
  return (
    <html lang="en" className={inter.className}>
      <body>
        <h1>404 - Page Not Found</h1>
        <p>This page does not exist.</p>
      </body>
    </html>
  )
}

// Import global styles and fonts
import './globals.css'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: '404 - Page Not Found',
  description: 'The page you are looking for does not exist.',
}

export default function GlobalNotFound() {
  return (
    <html lang="en" className={inter.className}>
      <body>
        <h1>404 - Page Not Found</h1>
        <p>This page does not exist.</p>
      </body>
    </html>
  )
}

Unlike not-found.js, this file must return a full HTML document, including <html> and <body> tags.

Reference

Props

not-found.js or global-not-found.js components do not accept any props.

Good to know: In addition to catching expected notFound() errors, the root app/not-found.js and app/global-not-found.js files handle any unmatched URLs for your whole application. This means users that visit a URL that is not handled by your app will be shown the exported UI.

Examples

Data Fetching

By default, not-found is a Server Component. You can mark it as async to fetch and display data:

import Link from 'next/link'
import { headers } from 'next/headers'

export default async function NotFound() {
  const headersList = await headers()
  const domain = headersList.get('host')
  const data = await getSiteData(domain)
  return (
    <div>
      <h2>Not Found: {data.name}</h2>
      <p>Could not find requested resource</p>
      <p>
        View <Link href="/blog">all posts</Link>
      </p>
    </div>
  )
}

import Link from 'next/link'
import { headers } from 'next/headers'

export default async function NotFound() {
  const headersList = await headers()
  const domain = headersList.get('host')
  const data = await getSiteData(domain)
  return (
    <div>
      <h2>Not Found: {data.name}</h2>
      <p>Could not find requested resource</p>
      <p>
        View <Link href="/blog">all posts</Link>
      </p>
    </div>
  )
}

If you need to use Client Component hooks like usePathname to display content based on the path, you must fetch data on the client-side instead.

Metadata

For global-not-found.js, you can export a metadata object or a generateMetadata function to customize the <title>, <meta>, and other head tags for your 404 page:

Good to know: Next.js automatically injects <meta name="robots" content="noindex" /> for pages that return a 404 status code, including global-not-found.js pages.

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Not Found',
  description: 'The page you are looking for does not exist.',
}

export default function GlobalNotFound() {
  return (
    <html lang="en">
      <body>
        <div>
          <h1>Not Found</h1>
          <p>The page you are looking for does not exist.</p>
        </div>
      </body>
    </html>
  )
}

export const metadata = {
  title: 'Not Found',
  description: 'The page you are looking for does not exist.',
}

export default function GlobalNotFound() {
  return (
    <html lang="en">
      <body>
        <div>
          <h1>Not Found</h1>
          <p>The page you are looking for does not exist.</p>
        </div>
      </body>
    </html>
  )
}

Version History

Version	Changes
`v15.4.0`	`global-not-found.js` introduced (experimental).
`v13.3.0`	Root `app/not-found` handles global unmatched URLs.
`v13.0.0`	`not-found` introduced.

Source: docs/01-app/03-api-reference/03-file-conventions/not-found.mdx

global-not-found.js (experimental)