Next.js 16+ · Function

notFound

The App Router's notFound function handles missing resources by throwing a framework 404 error. It stops rendering the current route segment and displays the nearest not-found UI.

How it works

Import notFound from next/navigation and invoke it during route rendering when the requested resource cannot be found. The call throws a special 404 error, stops rendering the current route segment, and lets the nearest not-found UI handle the response.

Syntax

notFound(): never

Returns

never

Key points

Use notFound to turn an absent resource into the route's 404 experience.
A typical trigger is a failed lookup for content, users, products, or another expected resource.
The function is control flow: it throws a framework-recognized error and stops the current segment's render.
Missing-resource responses are marked noindex automatically.
A segment-specific not-found file is optional; resolution walks upward to a parent boundary and then the default page.

Common mistakes

Do not wrap notFound in a catch-all try/catch unless you rethrow it; catching the thrown control-flow error prevents the not-found UI from rendering.
Calling notFound is sufficient; returning it is unnecessary because the function terminates execution by throwing.
If the response has already begun streaming, the UI can render while the HTTP status remains 200 rather than changing to 404.

Example: Render a 404 for a missing post

import { notFound } from 'next/navigation'

async function getPost(slug: string) {
  const response = await fetch(`https://example.com/api/posts/${slug}`)
  return response.ok ? response.json() : null
}

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

  if (!post) notFound()

  return <article><h1>{post.title}</h1></article>
}

Calls notFound when the requested post is unavailable, allowing the matching not-found boundary to render.

When to use it

Missing database or API resource

A dynamic page loads a record by slug or ID and the lookup returns no result.

404 from a Route Handler

A Route Handler cannot resolve the requested entity.

Custom not-found UI

A segment needs a tailored missing-resource screen.

Interview questions

QWhat does notFound do in the App Router?

notFound is a function imported from next/navigation that throws a special 404 error. It terminates rendering for the route segment where it is called, and the nearest not-found boundary supplies the UI.

Follow-up: How does it affect indexing? It causes Next.js to add a robots noindex meta tag, preventing the not-found response from being indexed.

QWhere can notFound be invoked?

Use it in the render path after loading a resource, such as when a database lookup returns no record. It works in Server Components, Server Functions, and Route Handlers.

Follow-up: What happens in a Route Handler? Calling it there serves a 404 response to the caller.

QHow do you customize the UI for a missing resource?

A route segment can provide a not-found file to customize the UI shown after notFound is called. Without a local file, the nearest parent boundary is used, eventually falling back to Next.js's default 404 page.

Follow-up: Does notFound need to be returned? No; it throws and stops execution, so a plain invocation is enough.

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

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