Error handling

An error screen from one file

Code fails sometimes. The tea shop's orders page reads the orders from a database, and once in a while the database doesn't answer. Then getOrders() throws an error: it stops and hands a JavaScript Error to whoever called it (try...catch shows how that works). The page waits for the orders, so it can't finish either. What should the visitor see?

In Next.js, the answer is one file. Put an error.tsx in a route's folder, and when something in that route throws, Next.js shows what error.tsx returns in its place. Here is the shop with one. Like every example in this lesson, it's a real Next.js 16.4.3 project, built with next build and run with next start. An error screen is drawn by React in the browser, so this one was also clicked through in real Chrome: open /, click Orders, then click Try again. The Steps tab opens right after the click on Orders.

1"use client";2 3export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {4  return (5    <main>6      <h1>Your orders did not load</h1>7      <p>Something went wrong on our side.</p>8      <button onClick={() => retry()}>Try again</button>9    </main>10  );11}

app/orders/error.tsx, the file shown first, is a component like any other, with two differences. Line 1, "use client", makes it a Client Component, because React draws error screens in the browser. And Next.js passes it props: line 3 takes retry, a function, and line 8 calls it when the visitor clicks Try again. Lines 6 and 7 are the screen itself.

Now click app/_data/orders.ts. It stands in for the shop's database. Line 3 counts the calls, and line 10 throws on the first one, the way a busy database fails once and then works again. app/orders/page.tsx waits for the orders on line 4, as in Loading UI, and app/orders/loading.tsx is the loading state from that lesson.

Here is what Chrome recorded, step by step:

• Step 2, click Orders: the page shows the links Home Orders, then Your orders did not load, Something went wrong on our side. and the Try again button. The page asked the server for the orders page. The server answered, and its answer said that getOrders() had thrown. React drew error.tsx in the page's place.
• Step 3, click Try again: the page shows Your orders and both orders. The click asked the server for the page again, and this time the database answered.

The links stayed on the screen the whole time. They come from the root layout, which sits outside error.tsx. Only the part that failed was replaced. The Steps tab also lists an error in Chrome's console for step 2: Next.js logs every error an error screen catches. In production it reads Minified React error #441: React's general message for a failed Server Component.

error.tsx is a Client Component error boundary

None of this is new to React. An error boundary is a React component that catches errors thrown while the components inside it are drawn, and shows a fallback, a screen to show instead. error.tsx is a shortcut for one. Written by hand, the tree Next.js builds for /orders is roughly this:

<RootLayout>
  <ErrorBoundary fallback={<OrdersError />}>
    <Suspense fallback={<Loading />}>
      <OrdersPage />
    </Suspense>
  </ErrorBoundary>
</RootLayout>

Line 1 is the root layout. Line 2 is an error boundary whose fallback is the component from error.tsx, here OrdersError. Line 3 is the Suspense boundary from loading.tsx, and line 4 is the page. This is a sketch to read, not code you write. It shows two things. The page and its loading state are inside the error boundary, so an error in either one shows OrdersError. The layout is outside, so it stays.

Why it must be a Client Component

React error boundaries run in the browser: they hold the error in their state, and React draws the fallback there. So error files must be Client Components, and Next.js checks this during the build. Here is the shop with line 1 of error.tsx removed. Open the Terminal tab:

1export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {2  return (3    <main>4      <h1>Your orders did not load</h1>5      <p>Something went wrong on our side.</p>6      <button onClick={() => retry()}>Try again</button>7    </main>8  );9}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ... > Build error occurredError: Turbopack build failed with 1 error:./app/orders/error.tsx:1:1Error: app/orders/error.tsx must be a Client Component. Add the "use client" directive the top of the file to resolve this issue.    Learn more: https://nextjs.org/docs/app/api-reference/directives/use-client>  1 | export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^>  2 |   return (     | ^^^^^^^^^^>  3 |     <main>     | ^^^^^^^^^^>  4 |       <h1>Your orders did not load</h1>     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^>  5 |       <p>Something went wrong on our side.</p>     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^>  6 |       <button onClick={() => retry()}>Try again</button>     | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^>  7 |     </main>     | ^^^^^^^^^^^>  8 |   );     | ^^^^>  9 | }     | ^  10 | Ecmascript file had an error     at ignore-listed frames

The build stops with app/orders/error.tsx must be a Client Component. Add the "use client" directive the top of the file to resolve this issue. The line is there to mark where the client part starts, as in every Client Component. Without it, the file would be a Server Component, which can't be an error boundary.

Next.js passes every error file the same props. Each row is one of them:

Which error.tsx catches it

An error goes up the tree until it meets an error boundary, the way a thrown error goes up through the functions that called it until a catch stops it. So the nearest error.tsx above the part that failed catches it. That includes the folders below it: app/error.tsx catches errors from every page that has no closer one. But an error.tsx doesn't cover the layout.tsx in its own folder, because the layout sits outside the boundary. The tea shop now has both app/error.tsx and app/orders/error.tsx. Pick each version and guess, before you look, which screen Chrome showed:

1import { getOrders } from "../_data/orders";2 3export default async function OrdersPage() {4  const orders = await getOrders();5  return (6    <main>7      <h1>Your orders</h1>8      <ul>9        {orders.map((order) => (10          <li key={order.id}>11            Order {order.id}: {order.tea}12          </li>13        ))}14      </ul>15    </main>16  );17}

With no error file at all, Next.js has its own: This page couldn’t load, with a Reload button, and nothing of the shop. When the page fails, app/orders/error.tsx catches it. When the orders layout fails, the error goes past app/orders/error.tsx, which sits inside that layout, to app/error.tsx: The shop hit a problem. The orders layout is gone from the screen, because the part that failed was the layout itself.

Each row is one place where an error can happen, and what Chrome showed for it:

Trying again: retry() and reset()

Some errors don't last: a database that was busy for a moment, a network that dropped one request. For those, a Try again button is the best error screen. Next.js gives every error file two functions for it, and they do different things. This version of the error screen has a button for each. It was opened at /orders in Chrome, where the first call to the database fails, then each button was clicked:

1"use client";2 3type Props = { error: unknown; retry: () => void; reset: () => void };4 5export default function OrdersError({ retry, reset }: Props) {6  return (7    <main>8      <h1>Your orders did not load</h1>9      <button onClick={() => reset()}>Draw it again</button>10      <button onClick={() => retry()}>Try again</button>11    </main>12  );13}

• reset(), line 9: it clears the error and asks React to draw the page again. React draws it from what it already has, and what it has is the server's answer that said getOrders() threw. So step 2 shows the same error screen, and asked the server for nothing: the only request it lists, if any, is a prefetch: a request the page's JavaScript makes early for a page that a link leads to.
• retry(), line 10: it asks the server for the page again, then draws the answer. Step 3 made one request for /orders that isn't a prefetch, the server ran the page again, the database answered, and the orders showed.

So use retry() for a Try again button. The page's data comes from the server, and only a new request can bring new data. reset() only helps when the error happened in the browser and drawing again might work. The other requests in step 3 are prefetches for the links, and Chrome's console lists React error #419 twice: React's note that the server couldn't finish part of the first HTML, so the browser drew that part itself.

When the root layout fails: global-error.tsx

app/error.tsx catches errors from every page, but not from the root layout: like every error file, it sits inside the layout of its own folder. The root layout holds the <html> and <body> of every page, so when it fails, nothing is left to draw a screen in. For that case, Next.js has one more file: app/global-error.tsx. It takes the root layout's place. Here the root layout shows who is signed in, and the sign-in service is down. Pick both versions:

1import { Suspense } from "react";2import Link from "next/link";3import { getCustomerName } from "./_data/customer";4 5export const metadata = { title: "Tea shop" };6 7async function SignedInAs() {8  const name = await getCustomerName();9  return <span>Signed in as {name}</span>;10}11 12export default function RootLayout({ children }: LayoutProps<"/">) {13  return (14    <html lang="en">15      <body>16        <nav>17          <Link href="/">Home</Link> <Link href="/orders">Orders</Link>{" "}18          <Suspense fallback={<span>Checking who you are…</span>}>19            <SignedInAs />20          </Suspense>21        </nav>22        {children}23      </body>24    </html>25  );26}

Without global-error.tsx, Next.js shows its own page: This page couldn’t load, A server error occurred. Reload to try again., a Reload button, and ERROR with a number, the error's digest: a code that leads to the real message in the server's log. With it, Chrome shows the shop's own screen. Because global-error.tsx replaces the root layout, it has to bring its own <html> and <body>, as lines 5 and 6 do.

The docs list what else follows from that:

• It doesn't get the root layout's styles and fonts. Import what it needs in the file itself.
• It can't export metadata, because it's a Client Component. To give it a title, put React's <title> inside it.
• It's for the root layout only. Keep an app/error.tsx for errors in pages, so the links stay.

Expected errors are values, not exceptions

Not every problem is an error to throw. The Next.js docs split them in two. Expected errors can happen while the app works as it should: a visitor types a wrong value into a form, or a tea sells out. Uncaught exceptions shouldn't happen at all: a bug, or a service that is down. Throw only the second kind, and let error.tsx catch it. Return the first kind as a value, and show it where it happened (Error strategies makes the same split in plain JavaScript).

Here is a form for ordering more Green tea, which accepts 1 to 10 boxes. The form is a Client Component that calls a Server Function, a function that runs on the server when the form is sent. A Server Function that a form calls is also called a Server Action.

"use client";

import { useActionState } from "react";
import { reorder } from "./actions";

export default function ReorderForm() {
  const [state, formAction, pending] = useActionState(reorder, { message: "" });
  return (
    <form action={formAction}>
      <label htmlFor="boxes">Boxes</label> <input id="boxes" name="boxes" defaultValue="1" />{" "}
      <button disabled={pending}>Order</button>
      {state.message && <p aria-live="polite">{state.message}</p>}
    </form>
  );
}

Line 7 passes the action, reorder, to useActionState. It gives back state, whatever the action returned last, starting as { message: "" }; formAction, which line 9 gives the form; and pending, which line 11 uses to turn the button off while the action runs. Line 12 shows state.message when there is one. Now the action, in two versions. Pick each one; the Steps tab opens after the click on Order:

1"use server";2 3export async function reorder(previous: { message: string }, formData: FormData) {4  const boxes = Number(formData.get("boxes"));5  if (!Number.isInteger(boxes) || boxes < 1 || boxes > 10) {6    return { message: "Choose between 1 and 10 boxes." };7  }8  // A real shop would save the order here.9  return { message: `Ordered ${boxes} boxes of Green tea.` };10}

In the first version, line 6 returns { message: "Choose between 1 and 10 boxes." }. The form shows the message, and the visitor can fix the number. In the second, line 6 throws the same text. The action's request answered 500, and app/error.tsx replaced the page with The shop hit a problem: no form, and no word about what was wrong. In production, the thrown message wouldn't even reach the browser: React replaces it with a general one.

Each row compares the two kinds:

The same goes for Server Components. A page whose data request answers "not available" can return a short message instead of throwing. A thing that doesn't exist at all, like an order number nobody has, has its own function, notFound(), which the next lesson teaches.

Errors in production: a digest instead of the message

An error's message can hold things the visitor must never see: a database address, a name, a piece of a query. So in production, Next.js keeps a Server Component's error message on the server. This error.tsx shows what it was given: line 4 reads error.message, and line 5 reads error.digest. The database is down for every request now. Open the Steps tab first, then the Terminal tab:

1"use client";2 3export default function OrdersError({ error }: { error: unknown }) {4  const message = error instanceof Error ? error.message : String(error);5  const digest = error instanceof Error && "digest" in error ? String(error.digest) : "none";6  return (7    <main>8      <h1>Your orders did not load</h1>9      <p>Message: {message}</p>10      <p>Error code: {digest}</p>11    </main>12  );13}

In the Steps tab, the message isn't The orders database did not answer. It's Minified React error #441. In production, React shortens its own messages to a number, and #441 means: "An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details." Under it is Error code with a number: the digest, a short code Next.js makes from the error.

Now the Terminal tab. After the build, next start printed the real error, twice (once for the recorder's plain request and once for Chrome): ⨯ Error: The orders database did not answer., where it was thrown, and digest: with the same number. That's what the digest is for. A visitor reports the code on the screen, and you search the server's logs for it to find the real message.

Three more things from this recording and the docs:

• In development the message is there. The docs say next dev sends the real message to the browser, to help you debug. Only production builds hide it, so test your error screens with next build and next start too.
• Client Components keep their message. An error thrown in the browser is already there, so the docs say it reaches error.tsx as it was thrown. It might not even be an Error, which is why line 4 checks error instanceof Error before it reads message.
• The page still answered 200. Pick the Network tab: GET /orders answered 200, and its HTML holds Loading your orders…, not the error screen. The layout and the loading state were sent before the page ran, with the status, and React drew the error screen in the browser.

Error screens across the tea shop

error.tsx replaces a whole route's page. Sometimes only one part of a page should get an error screen: the orders list can fail while the tea suggestions under it still work. For that, Next.js 16.3 added catchError, from next/error (16.2 had it as unstable_catchError). It makes an error boundary that you can put around any part of a page:

1"use client";2 3import { catchError, type ErrorInfo } from "next/error";4 5function OrdersFallback(props: object, { retry }: ErrorInfo) {6  return (7    <div>8      <p>Your orders did not load.</p>9      <button onClick={() => retry()}>Try again</button>10    </div>11  );12}13 14export default catchError(OrdersFallback);

In app/orders/orders-boundary.tsx, line 5 is the fallback. It gets two arguments: the props given to the boundary, and the same error, retry and reset an error.tsx gets. Line 9 calls retry(). Line 14 turns the fallback into a component. In app/orders/page.tsx, lines 22 to 26 put OrdersBoundary around the list only. In step 1, the list failed, and Chrome still showed the heading, the suggestions under it and the links. Step 2, Try again, brought the orders back. The docs add that catchError lets notFound() and redirect() through, which a plain React error boundary would catch by mistake.

Put together, a route's error files look like this. Each folder that needs its own screen gets an error.tsx, the root folder gets one for everything else, and global-error.tsx covers the root layout:

app/
  _data/
    customer.ts
    orders.ts
  orders/
    error.tsx
    loading.tsx
    page.tsx
  error.tsx
  global-error.tsx
  layout.tsx
  page.tsx

Now sort these problems: which ones should the code return as a value, and which ones should reach an error screen?

Common mix-ups

• "error.tsx catches errors in the layout beside it." No. It sits inside that layout. The failing orders layout went past app/orders/error.tsx to app/error.tsx.
• "error.tsx can be a Server Component." No. Error boundaries are Client Components, and without "use client" the build stops.
• "reset() loads the page again." No. It draws what React already has, and asked the server for nothing. retry() asks the server.
• "In production, error.message is the message I threw." No, not for a Server Component. It's React's general message; the real one is in the server's log, next to the digest.
• "A page that fails always answers 500." No. The recorded /orders answered 200: its layout and loading state were already on their way.
• "Every problem should throw." No. A wrong form value is expected. Return it, and the form can show it.
• "app/error.tsx covers the root layout." No. That's global-error.tsx's job, with its own <html> and <body>.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

app/
  _data/
    customer.ts
    orders.ts
  orders/
    error.tsx
    loading.tsx
    page.tsx
  error.tsx
  layout.tsx
  page.tsx

export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {
  return (
    <main>
      <h1>Your orders did not load</h1>
      <p>Something went wrong on our side.</p>
      <button onClick={() => retry()}>Try again</button>
    </main>
  );
}

"use client";

export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {
  return (
    <main>
      <h1>Your orders did not load</h1>
      <p>Something went wrong on our side.</p>
      <button onClick={() => retry()}>Try again</button>
    </main>
  );
}

"use client";

export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {
  return (
    <main>
      <h1>Your orders did not load</h1>
      <p>Something went wrong on our side.</p>
      {/* A button that asks the server for the orders again */}
    </main>
  );
}

"use client";

export default function OrdersError({ retry }: { error: unknown; retry: () => void }) {
  return (
    <main>
      <h1>Your orders did not load</h1>
      <p>Something went wrong on our side.</p>
      <button onClick={() => retry()}>Try again</button>
    </main>
  );
}

"use client";

type Props = { error: unknown; retry: () => void; reset: () => void };

export default function OrdersError({ retry, reset }: Props) {
  return (
    <main>
      <h1>Your orders did not load</h1>
      <button onClick={() => reset()}>Draw it again</button>
      <button onClick={() => retry()}>Try again</button>
    </main>
  );
}

import { Suspense } from "react";
import { getCustomerName } from "../_data/customer";

async function SignedInAs() {
  const name = await getCustomerName();
  return <p>Signed in as {name}</p>;
}

export default function OrdersLayout({ children }: LayoutProps<"/orders">) {
  return (
    <>
      <Suspense fallback={<p>Checking who you are…</p>}>
        <SignedInAs />
      </Suspense>
      {children}
    </>
  );
}

"use server";

export async function reorder(previous: { message: string }, formData: FormData) {
  const boxes = Number(formData.get("boxes"));
  if (!Number.isInteger(boxes) || boxes < 1 || boxes > 10) {
    throw new Error("Choose between 1 and 10 boxes.");
  }
  // A real shop would save the order here.
  return { message: `Ordered ${boxes} boxes of Green tea.` };
}

"use server";

export async function reorder(previous: { message: string }, formData: FormData) {
  const boxes = Number(formData.get("boxes"));
  if (!Number.isInteger(boxes) || boxes < 1 || boxes > 10) {
    return { message: "Choose between 1 and 10 boxes." };
  }
  // A real shop would save the order here.
  return { message: `Ordered ${boxes} boxes of Green tea.` };
}

Check your understanding

Key takeaways

• An error.tsx in a folder is the error screen of the route there. When something inside it throws, its screen takes that part's place, and the layouts around it stay.
• It's a React error boundary, so it must be a Client Component: without "use client", the build stops.
• The nearest error.tsx above the failing part catches the error. The layout in its own folder sits outside it, so a layout's error goes to the folder above.
• retry() asks the server for the part again and draws it; reset() only draws what React already has. Use retry() for Try again.
• global-error.tsx replaces the root layout when the root layout fails, with its own <html> and <body>.
• Return expected problems, like a wrong form value, as values. Throw only what the visitor can't fix.
• In production, a Server Component's message stays in the server's log. The browser gets React's general message and the same digest.

Coming next: Not found, forbidden and unauthorized. It shows notFound(), forbidden() and unauthorized(): three functions that stop a page, show the right screen, and decide the status code.