React Error Boundaries — The $120k Blank Dashboard

Production React apps break. A payment widget fetches malformed JSON, a third-party chart library throws on null data, a lazy-loaded component fails to parse — and suddenly your user sees a completely blank page with no explanation. No error message, no fallback, just white. That is the default behaviour of an unhandled render error in React, and it is brutal. A blank screen is worse than a visible error because users assume the whole product is broken, not just one widget.

What Is React Error Boundaries?

Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of the crashed component tree. They work like a try-catch block for the render phase — but only for class components. The two key methods are getDerivedStateFromError (to update state and render a fallback) and componentDidCatch (to log side effects). Here's a minimal example:

import React from 'react';

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

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, info) {
    console.error('Error caught by boundary:', error, info);
    // Send to monitoring service like Sentry
    logErrorToService(error, info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      return <div>Something went wrong. Please try again.</div>;
    }
    return this.props.children;
  }
}

How Error Boundaries Work Internally

When a component throws during rendering, React walks up the component tree looking for the nearest parent error boundary. If it finds one, React calls getDerivedStateFromError with the thrown error, then re-renders the boundary with the updated state (hasError = true). The fallback UI is rendered instead of the crashed subtree. If no boundary is found, React unmounts the entire tree and logs the error to the console. This 'catch-and-render' mechanism only applies to errors thrown in the commit phase — not during reconciliation itself. React uses a special work loop that catches thrown values and checks for boundary components that implement either componentDidCatch or getDerivedStateFromError.

Where to Place Error Boundaries in Your Component Tree

The placement of error boundaries is a strategic decision. You have two extremes: a single boundary at the root (global), which shows a full-page error for any crash, or granular boundaries around each widget. A common production pattern is a layered approach: - One boundary around the entire app to catch truly catastrophic failures. - Separate boundaries around each major section (header, sidebar, main content). - Additional boundaries around third-party widgets, charts, or data-heavy components. This lets the rest of the page remain interactive even if a widget fails. The trade-off is more code and potential memory overhead if you create too many boundary instances.

What Error Boundaries Cannot Catch

This is the most common source of confusion. Error boundaries do NOT catch: - Errors inside event handlers (e.g., onClick, onChange) — use try-catch inside the handler. - Errors in asynchronous code (setTimeout, Promises, async/await) — wrap the async block or use a global promise rejection handler. - Errors thrown during server-side rendering (SSR) — boundaries only work in the client. - Errors in the boundary component itself — the boundary cannot catch its own errors. - Errors thrown during event bubbling or in context providers — those are outside the render phase. For these cases, you need a separate error handling strategy: try-catch in event handlers, window.onerror for unhandled client exceptions, and error boundaries only for rendering.

function ClickHandler() {
  const handleClick = async () => {
    try {
      await fetchData();
    } catch (error) {
      // Error boundaries can't catch this, handle it here
      showToast('Fetch failed');
    }
  };
  return <button onClick={handleClick}>Load Data</button>;
}

Testing Error Boundaries

You should test that your error boundary correctly renders the fallback when a child throws. Use Jest with React Testing Library. The key is to simulate a rendering error in a child component. Then assert that the fallback UI appears. Also test that the componentDidCatch is called with the correct error. Here's an example:

import { render, screen } from '@testing-library/react';
import { ErrorBoundary } from './ErrorBoundary';

const ThrowComponent = () => {
  throw new Error('Test crash');
};

test('error boundary catches error and shows fallback', () => {
  render(
    <ErrorBoundary>
      <ThrowComponent />
    </ErrorBoundary>
  );
  expect(screen.getByText(/Something went wrong/i)).toBeInTheDocument();
});

Production Patterns with Error Boundaries

In production apps, a single error boundary is rarely enough. Common patterns include: - Retry pattern: After showing the fallback, give the user a 'Retry' button that resets the boundary state by calling setState({ hasError: false }). - Logging pattern: In componentDidCatch, send the error to your monitoring service along with the component stack. - Bulkhead pattern: Wrap each micro-frontend or module in its own boundary so that a failure in one doesn't affect others. - Reset pattern: If the error was a transient network failure, you can clear the error boundary after a timeout and re-mount the children by forcing a key change on the boundary's container.

import React from 'react';

export class RetryBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  handleRetry = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      return (
        <div role="alert">
          <p>Something went wrong.</p>
          <button onClick={this.handleRetry}>Retry</button>
        </div>
      );
    }
    return this.props.children;
  }
}

Why Error Boundaries Can't Touch Event Handlers or Async Code

You just shipped a feature. A user clicks a button, and the whole screen goes white. Your error boundary sat there doing nothing. Why? Because error boundaries only catch errors thrown during React's reconciliation phase — render, lifecycle methods, constructors, and effects. Event handlers run outside that phase. So do setTimeout, Promise chains, and requestAnimationFrame. If an error happens in an onClick handler, React has already committed the VDOM. There's no rendering to roll back. The error propagates to the window, not your boundary. Production apps handle this with a one-liner: wrap your async operations in try-catch and pipe errors into state (or a global error handler). Logging is cheap. White screens are not.

// io.thecodeforge

function Button({ label }) {
  const [error, setError] = useState(null);

  const handleClick = async () => {
    try {
      const data = await fetchOrder();
      // process data
    } catch (err) {
      setError(err);
    }
  };

  if (error) return <ErrorFallback error={error} />;

  return <button onClick={handleClick}>{label}</button>;
}

How react-error-boundary Saves You from Class Component Boilerplate

Maintaining a class component just for error handling feels like stepping back to 2018. The react-error-boundary library gives you a hook-based fallback that actually gets used in production. You wrap the boundary component around a tree. Pass a FallbackComponent or fallback prop. That's it. Under the hood, it still uses componentDidCatch — that's non-negotiable — but the API is declarative. You get onError for logging, onReset for retry logic, and resetKeys to clear state on prop changes. No more writing constructor+toggle state+render-if pattern in fifteen files. One import. One wrap. Keep your codebase modern. This is what your team should standardize on today.

// io.thecodeforge

import { ErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
  return (
    <div>
      <p>Something broke: {error.message}</p>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary
      FallbackComponent={Fallback}
      onError={(error) => console.error('Boundary caught:', error)}
      resetKeys={['userId']}
    >
      <Dashboard />
    </ErrorBoundary>
  );
}

The Two Real Limitations Nobody Talks About

Every blog post tells you boundaries don't catch async errors. Fine. But here's what hits you in production: boundaries cannot catch errors thrown inside the boundary component itself. If your ErrorBoundary's render fails, React has no fallback — it re-throws the error up the tree. Second: boundaries cannot catch errors in server-side rendered output. React throws a hard error during SSR, no boundary intervenes. This means your next.js or remix app during SSR hydration mismatch will kill the node process unless you have a global process.on('uncaughtException'). The fix? Keep your boundary component dead simple — no third-party deps, no state management, just a literal display. For SSR, implement a custom error page route. Don't let the docs fool you: boundaries are client-side only.

// io.thecodeforge

// BAD — boundary itself can fail
class FragileBoundary extends React.Component {
  componentDidCatch(error) {
    // imagine this fetch throws
    fetch('/log', { method: 'POST' });
  }
  render() {
    return <ExpensiveWidget />;  // if this throws, no recovery
  }
}

// GOOD — minimal boundary
class SolidBoundary extends React.Component {
  state = { hasError: false, error: null };
  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }
  render() {
    if (this.state.hasError) {
      return <p>Something went wrong.</p>;
    }
    return this.props.children;
  }
}