Error boundaries

If a component throws while React is rendering it and nothing catches the error, React unmounts the entire tree under that root. A bug in one sidebar widget becomes a blank page. An error boundary limits the damage: it catches errors thrown by the components below it and renders a fallback in their place, leaving the rest of the page alone.

Writing one

There is still no hook for this; a boundary is a class component that implements static getDerivedStateFromError (to switch to the fallback) and usually componentDidCatch (to log):

class ErrorBoundary extends React.Component<
  { fallback: React.ReactNode; children: React.ReactNode },
  { error: Error | null }
> {
  state = { error: null as Error | null };

  static getDerivedStateFromError(error: Error) {
    return { error };                          // render the fallback next
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    reportToMonitoring(error, info.componentStack);
  }

  render() {
    return this.state.error ? this.props.fallback : this.props.children;
  }
}

Most teams use the react-error-boundary package rather than writing this by hand. React 19 also lets you observe errors for a whole root with two createRoot options: onCaughtError (an error boundary caught it) and onUncaughtError (nothing did).

Which boundary catches it

An error goes to the nearest boundary above the component that threw. A boundary does not catch its own errors — if the boundary itself throws while rendering, the error goes to the boundary above it. Everything outside the failing boundary keeps rendering, and the boundaries further up never hear about it. The model below gives two boundaries the shape of the class above: getDerivedStateFromError runs while rendering and picks the fallback, componentDidCatch runs once the result is committed. The same broken weather widget is rendered on three versions of a page:

1let log = [];2let commitQueue = [];3 4// The two methods of a class boundary, as a plain object.5function makeBoundary(name, fallback) {6  return {7    state: { error: null },8    getDerivedStateFromError(error) {9      log.push(`render: ${name} switches to its fallback`);10      return { error };11    },12    componentDidCatch(error) {13      log.push(`commit: ${name} reports "${error.message}"`);14    },15    render(children) {16      return this.state.error ? [fallback] : children();17    },18  };19}20 21// <Boundary>{children}</Boundary>: render the children; if they throw,22// derive the error state, render again (now the fallback), and queue23// componentDidCatch for after the commit.24function within(boundary, children) {25  try {26    return boundary.render(children);27  } catch (error) {28    boundary.state = { ...boundary.state, ...boundary.getDerivedStateFromError(error) };29    commitQueue.push(() => boundary.componentDidCatch(error));30    return boundary.render(children);31  }32}33 34function renderRoot(App) {35  log = [];36  commitQueue = [];37  try {38    const screen = App();39    commitQueue.forEach((didCatch) => didCatch());40    return { screen, log };41  } catch (error) {42    log.push(`uncaught "${error.message}": the root unmounts`);43    return { screen: [], log };44  }45}46 47const Weather = () => {48  throw new Error("weather API returned 500");49};50 51export function run() {52  // Weather has its own boundary inside the page's boundary.53  const page = makeBoundary("PageBoundary", "Page unavailable");54  const widget = makeBoundary("WidgetBoundary", "Weather unavailable");55  const guarded = () =>56    within(page, () => ["Header", ...within(widget, Weather), "Article"]);57 58  // Only the page-level boundary.59  const pageOnly = makeBoundary("PageBoundary", "Page unavailable");60  const coarse = () => within(pageOnly, () => ["Header", ...Weather(), "Article"]);61 62  // No boundary at all.63  const bare = () => ["Header", ...Weather(), "Article"];64 65  return {66    widgetBoundary: renderRoot(guarded),67    pageBoundaryOnly: renderRoot(coarse),68    noBoundary: renderRoot(bare),69  };70}

What a boundary never sees

A boundary catches errors thrown while React renders the components below it, in their class lifecycle methods, and in their effects. It does not catch errors thrown:

• in event handlers — they run after rendering, outside React's render, so a try/catch in the handler is the tool;
• in asynchronous code such as setTimeout or a promise callback;
• in the boundary component itself.

To show a boundary's fallback for one of those, move the error into rendering: store it in state, or call a state setter with an updater that throws, which makes the next render throw. React 19's use(promise) does this for you — a rejected promise is thrown during render — and so does the startTransition returned by useTransition: an error thrown by its action is shown by the nearest boundary above that component.

The model below sketches why the handler case escapes (it is plain JavaScript, not React): the boundary is a try/catch around rendering, and a click handler runs later, outside it.

1export function run() {2  const log = [];3  let pendingThrow = null;  // a state updater that throws4 5  function boundaryRender(renderChild) {6    try {7      return renderChild();8    } catch (err) {9      return `fallback: ${err.message}`;10    }11  }12  function SaveButton() {13    if (pendingThrow) pendingThrow();   // React runs the updater during render14    return "button";15  }16 17  log.push(boundaryRender(SaveButton));18 19  // The click handler runs later, outside any render:20  try {21    (function onClick() { throw new Error("save failed"); })();22  } catch (err) {23    log.push(`escaped to the window: ${err.message}`);24  }25 26  // Re-throwing through state: setState(() => { throw err })27  pendingThrow = () => { throw new Error("save failed"); };28  log.push(boundaryRender(SaveButton));29  return log;30}

Placement and recovery

Put boundaries where a failure has a sensible fallback: around each route, each independent widget, each third-party embed. To try again, reset the boundary's state — the simplest way is to change its key, for example to the current route, so navigating away remounts it fresh.

Common mistakes

• No boundary at all, so any render error blanks the whole app.
• Expecting a boundary to catch an error from an onClick handler. It escapes, because the handler runs outside rendering (the second example models this); catch it in the handler or push it into state.
• One boundary at the root only. It works, but the fallback replaces the whole page instead of the one broken widget.
• A fallback that can itself throw (it reads the same broken data). The error goes to the next boundary up.

What interviewers ask

• What errors do error boundaries not catch? — Errors in event handlers, in asynchronous callbacks such as timers and promise callbacks, and in the boundary itself.
• Can you write an error boundary as a function component? — Not with React's own API: a boundary needs getDerivedStateFromError / componentDidCatch, which only class components have; a library such as react-error-boundary wraps that class for you.
• How would you show a fallback for a failed fetch in a click handler? — Catch it and put it in state (render an error message, or throw it from render so the nearest boundary shows its fallback).