Next.js 16+ · Directive

not-found

Use notFound() in the Next.js App Router to handle missing resources. It stops the current route segment and renders the nearest custom or default 404 UI.

How it works

The notFound function is a control-flow helper for missing resources in the App Router. Calling it throws a special 404 error, stops rendering the current route segment, and lets a nearby not-found file provide the response UI.

Syntax

notFound()

Returns

never; calling notFound() throws a special 404 error and does not return normally.

Key points

Use notFound() when a requested resource does not exist; it switches control flow to 404 handling.
The current route segment stops rendering immediately after the call.
Place a not-found file in a route segment to define its missing-resource interface.
The API supports the main server-side execution contexts in the App Router.
Boundary lookup proceeds upward when the local segment does not define custom not-found UI.

Common mistakes

The resulting 404 page is marked noindex automatically.
For streamed responses, the HTTP status may remain 200 even though the not-found UI is shown.

Example: Trigger a segment-level 404

import { notFound } from 'next/navigation'
import { getPostBySlug } from '@/lib/posts'

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = getPostBySlug(slug)

  if (!post) {
    notFound()
  }

  return <div>{post.title}</div>
}

Call notFound when the requested resource is missing; Next.js renders the nearest not-found UI for the route segment.

When to use it

Missing resource pages

A database or API lookup returns no matching record.

Route Handler 404 responses

A server endpoint must signal that a requested entity does not exist.

Segment-specific 404 UI

A nested route needs its own branded missing-content screen.

Interview questions

QWhat does notFound() do?

notFound() throws a special 404 error and ends rendering for the route segment where it runs. A matching not-found file supplies the segment's UI.

Follow-up: How can a route handler use it? It can call notFound() to return a 404 response to the caller.

QHow do you customize the 404 UI?

Create not-found.js or not-found.tsx in the relevant route segment. When notFound() is invoked there, Next.js renders that boundary's UI.

Follow-up: What happens if the segment has no file? The nearest parent not-found boundary is used, otherwise Next.js falls back to its default 404 page.

QWhere can notFound() be called?

The function is available in Server Components, Server Functions, and Route Handlers. It should be called on the render path when a resource lookup shows that the resource is absent.

Follow-up: What metadata accompanies the result? Next.js adds a robots noindex meta tag to prevent indexing.

not-found.js
global-not-found.js
error.js
Route Handlers
Server Components

Source: Functions: notFound. Checked 2026-10-15.