React Error Boundaries: Catch and Handle Runtime Errors Gracefully

In React applications, an unhandled JavaScript error thrown during rendering, in a lifecycle method, or in the constructor of a child component will cause the entire React component tree to unmount, leaving users with a blank white page. Before React 16, errors in components propagated unpredictably and left the UI in a corrupted state. React 16 introduced Error Boundaries as a formal mechanism for catching these rendering errors and displaying a fallback user interface instead of an empty screen. An error boundary is a React class component that implements either or both of the getDerivedStateFromError and componentDidCatch lifecycle methods. When an error is thrown anywhere in the subtree below an error boundary, the boundary catches it, transitions to an error state, and renders a specified fallback UI. This allows you to isolate failure to the affected portion of the page without bringing down the entire application.

Creating Your First Error Boundary

Error boundaries must be class components because there is currently no equivalent hook API for the componentDidCatch lifecycle. Create a class that extends React.Component and adds a state property called hasError initialized to false. Implement the static getDerivedStateFromError method, which receives the thrown error and returns a state update object. Returning the object with hasError set to true causes the component to re-render with the error state. In the render method, check hasError and return the fallback UI when true, or render children normally when false. The componentDidCatch lifecycle method fires after the error has been caught and receives both the error object and an info object containing a componentStack string that shows the component hierarchy at the point of the error. Use componentDidCatch to send the error details to your error monitoring service such as Sentry or Datadog.

What Error Boundaries Do Not Catch

Error boundaries have several important limitations that you must understand to avoid false confidence in your error handling. They do not catch errors inside event handlers. An onClick callback that throws will not be caught by any error boundary because event handlers are called by the browser outside of the React rendering lifecycle. Use regular try-catch blocks inside event handlers for those errors. Error boundaries do not catch errors thrown in asynchronous code, including setTimeout callbacks, Promise rejections, and the bodies of async functions. They do not catch errors in the error boundary component itself. They do not catch errors during server-side rendering. And they do not catch errors in React hooks such as useEffect, whose asynchronous error handling requires different patterns. Understanding these boundaries helps you design a complete error handling strategy that combines error boundaries for rendering errors with try-catch and Promise rejection handlers for asynchronous operations.

Placement Strategy: Where to Put Error Boundaries

The placement of error boundaries in your component tree determines the scope of failures they contain. Wrapping the entire application in a single top-level error boundary catches all unhandled rendering errors and prevents a blank page, but also means that any error anywhere takes down the visible UI entirely. A more granular strategy wraps each major page section in its own error boundary. This way, if the comments section of a blog post throws an error, only the comments section shows a fallback while the rest of the article remains readable and functional. For third-party widgets, data visualization charts, and complex interactive components that have a higher probability of throwing, dedicated error boundaries confine the failure blast radius. A useful mental model is to think about the user experience you want when each section fails and place boundaries accordingly, with more critical sections receiving more isolated boundaries.

Using react-error-boundary for Functional Components

The react-error-boundary library by Brian Vaughn wraps the class component error boundary pattern in a convenient component and hook API, making it easier to integrate with functional component architectures. The ErrorBoundary component accepts a FallbackComponent prop that renders when an error is caught, and a onError prop for the error logging callback. The fallback component receives error and resetErrorBoundary as props. Calling resetErrorBoundary resets the error state and attempts to re-render the children, allowing users to recover from transient errors without a full page reload. The useErrorBoundary hook, provided by the library, lets functional components programmatically throw errors into the nearest error boundary, making it possible to trigger error boundary fallbacks from async code and event handlers, not just rendering errors.

Fallback UI Design: What to Show When Things Break

The fallback user interface shown during an error state significantly impacts user experience and trust. A generic white error page with no guidance is frustrating and unhelpful. A good fallback UI explains that something went wrong in plain, non-technical language, provides a clear action the user can take such as refreshing the page or navigating home, and ideally offers a way to report the problem. For section-level error boundaries, the fallback should be appropriately scoped and not imply that the entire application has failed when only one widget is broken. Include a retry button that calls the error boundary reset mechanism. For authenticated applications, a link to the home page or dashboard gives users an escape route. Keep the fallback component simple and avoid network requests or complex state that could itself throw an error inside the error boundary.

Integrating with Error Monitoring Services

Error boundaries become far more valuable when connected to a centralized error monitoring service like Sentry, Bugsnag, or Datadog. These services capture the full error details including stack trace, component hierarchy, browser environment, user session information, and the sequence of actions that led to the error. In the componentDidCatch method or the onError callback of react-error-boundary, call your monitoring service SDK to report the error. Always send the componentStack from the error info object along with the error itself, as it provides the React component hierarchy at the point of failure. Configure your monitoring service to group similar errors together and set up alerting thresholds so that a sudden spike in error rate from a bad deployment triggers an immediate notification. Correlating error boundary reports with your deployment history helps you identify which code change introduced a regression.