Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 39 ยท Error Handling and Boundaries

Error Boundaries in Routes

Learn how route-level ErrorBoundary exports catch loader, action and render errors, why the nearest boundary wins, and how the rest of the page keeps working.

Every app fails sometimes. A database call times out, a record is missing, a component reads a property of undefined. In a plain React app one such mistake can blank the whole screen. In Remix and React Router framework mode you get a more forgiving design: every route can export its own ErrorBoundary, and when something in that route fails, only that part of the page is replaced by the boundary's output. The navigation, the layout around it and even sibling routes stay alive.

This lesson shows what a boundary catches, how the router picks which boundary renders, and how to model that behavior with a small runnable stand-in. The real framework code is shown read-only because the live editor cannot run a React Router server. The runnable blocks are plain JavaScript that imitates the same idea and say so.

What a route boundary catches

A route module is a file with named exports. Next to loader, action and the default component you may export ErrorBoundary. It catches errors from three places in that route and everything below it:

  • the loader and action (thrown while fetching or mutating data),
  • the route component while it renders,
  • the components rendered by child routes that have no boundary of their own.
TSX
// app/routes/projects.$id.tsx - React Router framework mode (read-only)
import { isRouteErrorResponse } from "react-router";
import type { Route } from "./+types/projects.$id";

export async function loader({ params }: Route.LoaderArgs) {
  const project = await findProject(params.id);
  if (!project) {
    throw new Response("Not found", { status: 404 });
  }
  return project;
}

export default function Project({ loaderData }: Route.ComponentProps) {
  return <h1>{loaderData.name}</h1>;
}

export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
  if (isRouteErrorResponse(error)) {
    return <p>{error.status}: {error.statusText}</p>;
  }
  return <p>Something went wrong.</p>;
}

The boundary receives the thrown value as error. In older Remix code you read it with the useRouteError() hook; both give the same value.

The nearest boundary wins

Routes nest, so boundaries nest too. When an error happens in a route, the router walks up the route tree from that route until it finds a module that exports ErrorBoundary. That boundary renders in the place where the failed route would have rendered. Layouts above it keep rendering normally.

flowchart TD
  R["root (has ErrorBoundary)"] --> L["dashboard layout"]
  L --> A["dashboard/reports (loader throws)"]
  L --> B["dashboard/settings"]
  A -. "no boundary here, bubble up" .-> L
  L -. "no boundary here, bubble up" .-> R
  R -->|"root boundary renders"| Out["whole page replaced"]

If neither reports nor its layout export a boundary, the error bubbles to the root and the full page is replaced. Add a boundary to the layout and only the content area changes.

The root route is special. Because it renders the <html> document, its boundary must render a complete document too, or you export Layout from the root so both the normal page and the error page share the same shell.

Node.js Stand-in: find the nearest boundary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Rendering errors and the hydrated page

A boundary also catches errors thrown while a component renders in the browser. It works like a React error boundary, with one difference you should know: it replaces only that route's segment, and navigating to another route clears the error. The router resets the boundary whenever the location changes, so a user is never stuck on a broken screen.

Errors in event handlers (an onClick that throws) and in plain setTimeout callbacks are not caught by any boundary. React does not route those to boundaries. Handle them yourself with try/catch and show an inline message.

Designing a good boundary

A boundary is part of your product, so write it like a page:

  1. Say what happened in human words, not a stack trace.
  2. Offer a way out: a link to the parent list or the home page.
  3. Keep it light. It renders when your code is already misbehaving, so avoid data fetching in it.
  4. Never print error.stack in production. Stack traces reveal file paths and library versions.
Node.js Stand-in: a friendly boundary

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In framework mode you can throw a Response or use the data() helper. Both reach the boundary as a route error response. The next lesson covers them in detail.

Common mistakes

  • Only a root boundary. One catch-all means any failure replaces the whole page. Add boundaries at layout level.
  • Boundary that throws. If the boundary itself errors, the error bubbles to the next boundary up. Keep it simple.
  • Catching what should be validated. A form with a missing field is not an exception. Return the errors from the action instead.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which boundary renders when a loader fails in a nested route?

    The router bubbles up from the failing route and uses the first route module that exports ErrorBoundary. Layouts above it keep rendering.
  2. 2. Which error is NOT caught by a route ErrorBoundary?

    Event handler errors are outside React's render phase, so no boundary sees them. Use try/catch there.
  3. 3. What happens to a displayed boundary when the user navigates elsewhere?

    Route boundaries reset on navigation so a user can recover by clicking a link.
  4. 4. Why must the root boundary render a full document?

    The root route owns html, head and body. If it fails, its boundary (or the exported Layout) must supply them.

Summary

  • A route may export ErrorBoundary to catch loader, action and render errors in its subtree.
  • The nearest boundary above the failing route renders in its place; layouts above survive.
  • Event handler errors are not caught; handle them with try/catch.
  • Boundaries reset on navigation. Keep them friendly, simple and free of stack traces.
  • Put boundaries at layout level, not only at the root.

Next: Throwing Responses and 404 Pages