Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

How do loading.js, error.js and not-found.js map onto Suspense and error boundaries?

Questions in this chapter (6)
  • Draft
  • medium
  • Askedvery often
  • Verified November 2026

Answer

Each file is a boundary Next.js inserts for you, in this order under the segment's layout and template: error.js (an error boundary), then loading.js (a <Suspense> boundary whose fallback is the file), then not-found.js, then the page or the child segment. What the files add on top of React:

  • loading.js. The fallback is part of the prefetched route, so a <Link> click shows it at once while the page renders on the server and streams in. On a first load it's in the initial HTML and the page streams in later. Because it sits below the segment's layout, it can't cover a slow layout in the same folder; the parent's loading.js can.
  • error.js. Must be a Client Component. It catches errors from rendering the page and child segments, including Server Component errors, which Next.js forwards to the client: in production error.message is React's generic error #441 and error.digest matches the server log. retry() refetches and re-renders the segment; reset() only clears the error state. It doesn't catch its own layout's errors: the parent's error.js does, and global-error.js covers the root layout.
  • not-found.js. Renders when notFound() is thrown in the segment or below, and for unmatched URLs at the root. Next.js adds <meta name="robots" content="noindex">.

The status code depends on when the boundary triggers. Before anything has streamed, notFound() yields a real 404. Once a loading.js or <Suspense> fallback has been sent, the headers are gone, so the response stays 200 and the not-found UI streams in with noindex. With Cache Components, the prerendered shell is sent first, so a request-time notFound() also gives 200. To return a real 404 there, check before streaming starts, for example in proxy.ts.

Example

// app/products/loading.jsx
export default function Loading() { return <p>Loading product…</p>; }

// app/products/error.jsx
'use client';
export default function Error({ error, retry }) {
  return <p>Failed ({error.digest}) <button onClick={() => retry()}>Retry</button></p>;
}

// app/products/not-found.jsx
export default function NotFound() { return <p>No such product.</p>; }

// app/products/[slug]/page.jsx
import { notFound } from 'next/navigation';
export default async function Product({ params }) {
  const { slug } = await params;
  const product = await getProduct(slug); // uncached, ~500 ms
  if (!product) notFound();
  return <h1>{product.name}</h1>;
}

Next.js 16.4.5 under next start, Cache Components off, timed with a streaming fetch. /products/mug sent 200 headers and the fallback at 0.08 s and <h1>Mug at 0.57 s. /products/nope also answered 200; its noindex tag streamed in at 0.56 s. /products/boom answered 200 and Chrome 156 and Firefox 159 showed Failed (2773840547), the digest the server logged. Without the loading.jsx, /nf/x (same shape) answered 404.

Pitfalls

  • Expecting loading.js to cover its own layout. A layout awaiting uncached data blocked a <Link> navigation for 1–2 seconds with the old page still showing; the same-folder fallback never appeared.
  • Expecting error.js to catch its own layout. An error thrown in app/err/layout-throw/layout.jsx rendered app/err/error.jsx, not the sibling file.
  • Relying on notFound() for a 404 status in a streamed page. The response was 200 with noindex; crawlers may count it as a soft 404.
  • Showing error.message to users. In production a Server Component error's message is generic; log and match on digest.

Follow-ups

What's the difference between retry() and reset()?
retry(), stable since 16.3, re-fetches the segment from the server and re-renders it, so a transient failure can recover. reset() only clears the boundary's state and re-renders with what the client already has.
Why does every page download not-found.js?
The docs say each not-found.js is sent with every route under its segment. The No such product. text was in the /products/mug response too. Keep a root not-found.js light.
Do these boundaries catch errors in event handlers?
No. Like any React error boundary, they catch rendering errors; errors in event handlers or after an await in a callback need your own try/catch.

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.