Error Boundaries — React Deep Dive

the catch net: why error boundaries exist

When a component throws during render, React unmounts the entire component tree — the whole screen goes white. An error boundary is a class component that acts as a try/catch for its subtree: it catches the error and renders a fallback UI instead of crashing the app. Define static getDerivedStateFromError(error) to update state (pure — return the new state), and componentDidCatch(error, info) for side effects (logging, analytics).

error source	caught by boundary?	where to handle instead
render phase (JSX, function body)	YES	—
lifecycle methods (constructor, render, shouldComponentUpdate…)	YES	—
child component constructors + render	YES	—
event handlers (onClick, onSubmit…)	NO	`try / catch` inside the handler
async code (fetch, await, promises)	NO	`.catch()` / `try / catch`
setTimeout, setInterval, requestAnimationFrame	NO	`try / catch` inside the callback
errors thrown IN the boundary itself	NO	a parent boundary, or it crashes

1 · the boundary you write (edit me)

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  // PURE: return the new state. Called during render phase.
  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  // SIDE EFFECT: log to analytics. Called after commit.
  componentDidCatch(error, info) {
    console.log('ErrorBoundary caught:', error.message);
    console.log('Component stack:', info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      return (
        <div data-testid="fallback" className="p-4 bg-red-900 rounded-lg border border-red-500 text-red-100">
          💥 Error caught! Component recovered.
        </div>
      );
    }
    return this.props.children;
  }
}

function BombComponent(props) {
  // Throws DURING render — this is what the boundary catches.
  if (props.shouldThrow) {
    throw new Error('Kaboom! Render error caught by boundary.');
  }
  return (
    <div data-testid="safe" className="p-4 bg-[#0d1117] rounded-lg border border-[#30363d]">
      ✅ Safe — click "Trigger Error" to crash me
    </div>
  );
}

function App() {
  const [shouldThrow, setShouldThrow] = React.useState(false);
  const [resetKey, setResetKey] = React.useState(0);

  return (
    <div className="max-w-sm mx-auto p-5">
      {/*
        key={resetKey} is the recovery mechanism:
        changing the key unmounts the boundary and mounts a FRESH one
        (hasError resets to false). The buttons are OUTSIDE the boundary
        so they survive the crash.
      */}
      <ErrorBoundary key={resetKey}>
        <BombComponent shouldThrow={shouldThrow} />
      </ErrorBoundary>

      <div className="flex gap-2 mt-4">
        <button
          data-testid="trigger"
          className="px-4 py-2 bg-[#e74c3c] text-white rounded font-bold text-sm hover:opacity-80"
          onClick={function () { setShouldThrow(true); }}
        >
          Trigger Error
        </button>
        <button
          data-testid="reset"
          className="px-4 py-2 bg-[#61dafb] text-[#0d1117] rounded font-bold text-sm hover:opacity-80"
          onClick={function () {
            setShouldThrow(false);
            setResetKey(resetKey + 1);
          }}
        >
          Reset
        </button>
      </div>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<App />);

2 · Babel compiles JSX → element tree

<ErrorBoundary> becomes React.createElement(ErrorBoundary, { '{ key: resetKey }' }). When BombComponent throws, React unwinds to the nearest boundary and re-renders it with hasError: true.

// (hit "compile & render" to see Babel's output)

3 · live React (catch → fallback → recover)

Click "Trigger Error" to make BombComponent throw during render. The boundary catches it and shows the fallback. Click "Reset" to remount the boundary (new key) and recover. The gold-check does this automatically: assert safe → crash → assert fallback → reset → assert safe.

state: — · gold: safe → trigger → fallback → reset → safe

lifecycle → pattern

step	method	role
1 · catch	`static getDerivedStateFromError(error)`	PURE — return `{'{ hasError: true }'}` to switch to fallback
2 · log	`componentDidCatch(error, info)`	SIDE EFFECT — send to Sentry/analytics; `info.componentStack` has the trace
3 · render	`if (this.state.hasError) return <Fallback/>`	show fallback UI instead of the crashed children
4 · recover	change `key` on the boundary	remounts the boundary — `hasError` resets to `false`
React 19	`createRoot(el, { '{ onCaughtError }' })`	root-level callback for caught errors (replaces default `console.error`)