Error boundaries: the class-only net and its four blind spots

Why React unmounts everything — and what a boundary is

React 16 made a deliberate call: a corrupted UI is worse than no UI. If a render throws and nothing catches it, React cannot know which part of the committed tree is now lying to the user — a payment form might show the wrong amount, a medical dashboard the wrong patient. So it unmounts the whole root. An error boundary is how you opt back into partial survival: a component that tells React “if anything below me throws during rendering, I will render something sane instead.”

A boundary is a class component that implements one or both of two lifecycles, and they split the work along React’s render/commit phases:

class WidgetBoundary extends React.Component {
  state = { error: null };

  static getDerivedStateFromError(error) {
    // render phase: must be pure — derive fallback state, nothing else
    return { error };
  }

  componentDidCatch(error, errorInfo) {
    // commit phase: side effects allowed — report once, with the React tree
    reportError(error, errorInfo.componentStack);
    // componentStack reads like: "in PriceTag / in Card / in Carousel / in App"
  }

  render() {
    if (this.state.error) return <CarouselFallback />;
    return this.props.children;
  }
}

getDerivedStateFromError(error) runs during the render phase, while React is unwinding from the throw — it must be pure, and its job is to return state that switches render() onto the fallback branch. componentDidCatch(error, errorInfo) runs in the commit phase, where side effects are legal — that is where reporting belongs, and it is the only place that hands you errorInfo.componentStack: the chain of components that contained the crash, which is different from the JS stack (the chain of function calls that produced it). You usually want both in the report.

Why class-only? Because catching a render-phase throw needs a lifecycle that the reconciler can invoke synchronously mid-unwind. A function component has no such attachment point — its entire body is the render, so there is nowhere to hang the catch without re-running the body. There is no hook equivalent, and the React docs are explicit about it. Every function-component “boundary” you have seen wraps a class internally.

The four blind spots

Boundaries catch errors thrown during rendering, in lifecycle methods, and in constructors of the tree below them. Everything else escapes, and the four escapes surprise teams in production. Before you ship a boundary, ask yourself: does the thing most likely to crash in this widget live inside render — or in a handler, an async call, or the fallback itself?

1. Event handlers. An onClick throw happens outside rendering — React has no tree to repair, so it does not involve boundaries at all. The error propagates to window as an uncaught exception, the UI stays exactly as it was, and the user gets a button that “does nothing”. You own the try/catch.
2. Async code. setTimeout callbacks, promise chains, the body of an async effect — by the time these throw, the render call stack is long gone. Rejected promises surface as unhandledrejection, not as a caught render error.
3. Server-side rendering. Class boundaries are a client-runtime mechanism. During streaming SSR an error is handled by the server entry point (onError of the stream API) and the nearest Suspense fallback — not by your componentDidCatch.
4. The boundary itself. A throw inside the boundary’s own render — most often inside a fancy fallback — propagates to the next boundary above. If the root boundary’s fallback fetches translations and that fetch code throws, you are back to the white screen. Fallbacks must be boring on purpose.

Together these four categories mean that a boundary alone is not a complete error strategy — it handles the render path, and you own every other path explicitly. Miss even one and you get a silently dead UI with a healthy error dashboard.

The first two blind spots have a practical bridge. The de-facto standard wrapper, react-error-boundary, packages the class for you and adds the routing primitive:

import { ErrorBoundary, useErrorBoundary } from "react-error-boundary";

function ExportButton() {
  const { showBoundary } = useErrorBoundary();
  return (
    <button
      onClick={async () => {
        try {
          await exportReport();   // handler + async: two blind spots at once
        } catch (err) {
          showBoundary(err);      // route it INTO the nearest boundary
        }
      }}
    >
      Export
    </button>
  );
}

<ErrorBoundary
  FallbackComponent={ReportFallback}  // receives { error, resetErrorBoundary }
  onError={(error, info) => reportError(error, info.componentStack)}
>
  <ReportPanel />
</ErrorBoundary>

showBoundary(err) makes the nearest boundary render its fallback as if the error had happened in render — one consistent fallback path for render crashes and the failures you caught manually. onError centralizes reporting so each boundary does not reinvent it.

Placement: route tier plus widget tier

Where you put boundaries is an availability design decision, because each boundary defines a blast radius and owes the user a meaningful fallback:

• Root tier — the last resort. Fallback is a full-page “something broke, reload” screen. Blast radius is still 100%, but a designed 100% instead of a white screen. Every app needs exactly one.
• Route tier — one boundary per page-level route. The shell, navigation and other routes stay alive; the fallback offers a path back. Blast radius: one page.
• Widget tier — around independent, risky islands: third-party embeds, charts fed by external data, anything rendering user-generated content. The Hook’s carousel belongs here. Blast radius: one card out of twenty.

The anti-pattern is wrapping every component “to be safe”: dozens of generic “oops” fallbacks fragment the page into apologetic holes, and nobody designs a real recovery for any of them. Tiers force the right question per tier — what can the user still do here?

One production nuance: in development the React DevTools overlay surfaces errors even when a boundary catches them — teams regularly conclude their boundary is broken when it is working as designed. In production the user sees only your fallback; the message itself is minified to an error code plus a decoder link, and componentStack is only readable after source maps are applied. React 19 also cleaned up reporting: caught errors are logged once through the root’s onCaughtError instead of duplicated to the console — the pipeline side of that story is lesson 03.