Skip to content
Here Be Dragons

Modern React 33: Error boundaries and recovery

This is part 33 of the Modern React development series.

A React render can fail because a component throws. Error boundaries catch those render-time failures below a chosen point in the tree and replace that region with fallback UI instead of losing the whole app.

Concept

An error boundary is a component boundary that catches errors thrown while rendering, in lifecycle methods, or in constructors of class components below it. React’s current docs also connect root error callbacks and router or framework error files to production reporting.

Terms

  • Error boundary: A boundary that catches render-time errors from descendants and renders fallback UI.
  • Fallback UI: The replacement UI shown when the boundary catches an error.
  • Recovery: The path that lets the user retry, navigate away, or reset the failed region.
  • Root error callback: A createRoot option for reporting caught, uncaught, or recoverable errors in production.

Mental model

Think of an error boundary as a circuit breaker for a section of UI. When a child throws, the boundary trips and keeps the rest of the page powered.

How it is used

Use error boundaries around route regions, dashboards, widgets that rely on external data, embeddable components, and product areas where a local fallback is better than a blank app.

How to use it

  1. Place boundaries around user-meaningful UI regions.
  2. Render fallback UI that explains the failed region and offers a next action.
  3. Add a reset path, such as a retry key, route navigation, or explicit reset button.
  4. Report caught errors with component stack information.
  5. Pair error boundaries with Suspense when the region also has loading behavior.

Example: Boundary usage

import { ActivityPanel } from "./ActivityPanel";
import { ErrorBoundary } from "./ErrorBoundary";
import { PanelError } from "./PanelError";
import { RevenuePanel } from "./RevenuePanel";


export function DashboardPage() {
  return (
    <main>
      <h1>Dashboard</h1>
      <ErrorBoundary fallback={<PanelError />}>
        <RevenuePanel />
      </ErrorBoundary>
      <ErrorBoundary fallback={<PanelError />}>
        <ActivityPanel />
      </ErrorBoundary>
    </main>
  );
}
React output

Dashboard

Revenue

$53,000 this week

Activity

12 updates today

Separate boundaries let one panel fail without replacing the whole dashboard.

Example: Root production reporting

import { createRoot } from "react-dom/client";


createRoot(document.getElementById("root")!, {
  onCaughtError(error, errorInfo) {
    reportError({
      error,
      componentStack: errorInfo.componentStack,
    });
  },
}).render(<App />);
Browser result
createRoot(document.getElementById("root")!, {
  onCaughtError(error, errorInfo) {
    reportError({
      error,
      componentStack: errorInfo.componentStack,
    });
  },
}).render(<App />);

Root callbacks are a production reporting hook. They do not replace user-facing recovery UI.

Details to watch

  • Error type: Error boundaries catch render-time errors, not every async error in event handlers or server code.
  • Boundary size: A boundary should map to a region the user can understand.
  • Reset: Fallback UI without a recovery path can trap the user in an error state.
  • Framework routes: Frameworks often provide route-level error files or boundary APIs. Use the local convention.

Series navigation

References

Why the name "Here Be Dragons"?