How to Debug Error Boundaries in React

Error boundaries in React are crucial for catching JavaScript errors in child component trees, preventing entire application crashes. However, debugging them can be tricky because React behaves differently in development and production environments, and the React DevTools overlay can sometimes obscure your fallback UI. This article provides a straightforward guide on how to effectively inspect, test, and debug React Error Boundaries using built-in lifecycle methods, browser tools, and local production builds.

1. Understand the Development vs. Production Behavior

Before debugging, you must understand how React handles errors in different environments:

• In Development: React will always display a full-screen, interactive “Error Overlay” (the red screen) even if your Error Boundary catches the error. You can temporarily dismiss this overlay by clicking the “X” in the top-right corner to inspect your fallback UI.
• In Production: The error overlay is completely disabled. Users will only see the fallback UI rendered by your Error Boundary.

To see exactly what your users will see, run a production build locally:

npm run build
npx serve -s build

2. Inspect Error Details via Lifecycle Methods

An Error Boundary is a class component that implements getDerivedStateFromError and componentDidCatch. To debug errors passing through your boundary, place console logs inside these methods.

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

  static getDerivedStateFromError(error) {
    // Update state so the next render will show the fallback UI.
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    // 1. Log the error to the console for debugging
    console.error("Caught by Error Boundary:", error);
    console.group("Component Stack Trace");
    console.error(errorInfo.componentStack);
    console.groupEnd();

    // 2. You can also send the error to an external logging service here
  }

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

The componentStack property in errorInfo is especially useful because it provides a precise component-tree trace pointing directly to the failing component.

3. Use React Developer Tools to Trigger Errors

You can use the official React Developer Tools browser extension to manually force components to throw errors.

1. Open your browser’s Developer Tools and navigate to the Components tab.
2. Select any component inside your Error Boundary.
3. In the right-hand panel, click the “Force selected component to throw an error” button (which looks like a small warning sign or lightning bolt, depending on the version).
4. Verify that your Error Boundary catches the simulated crash and displays the expected fallback UI.

4. Debug State and Props in the Fallback UI

When an error is caught, you may want to inspect the state of the Error Boundary itself.

1. Open the Components tab in React DevTools.
2. Find your <ErrorBoundary> component in the tree.
3. Inspect its state. You should see hasError: true.
4. You can manually toggle this state value from true to false in the DevTools panel to test the transition between the error state and the normal application state.

5. Identify Uncaught Errors

Remember that Error Boundaries do not catch errors for: * Event handlers (e.g., onClick functions) * Asynchronous code (e.g., setTimeout or fetch promises) * Server-side rendering * Errors thrown in the Error Boundary itself (rather than its children)

If your Error Boundary is not catching an error, ensure the crash is not occurring in one of these unsupported areas. To handle errors in async code or event handlers, you must use standard try/catch blocks or pass the error to the local state to trigger a re-render that the Error Boundary can intercept.