Error Boundaries

Introduction

JavaScript errors happen — a field is unexpectedly undefined, an API returns a different shape than expected, a third-party library throws. In a well-behaved application, one broken widget should not take down the entire page. But by default, that is exactly what React does.

This lesson introduces error boundaries: special components that catch JavaScript errors thrown anywhere in their child component tree during rendering, log them, and display a fallback UI instead of leaving users staring at a blank screen.

The Problem: One Error Crashes Everything

React renders your component tree top to bottom. If any component throws an error while rendering — say, calling .toUpperCase() on a value that turned out to be undefined — React does not know how to safely continue, so by default it unmounts the entire component tree, leaving a blank white screen with no explanation for the user.

function UserBadge({ user }) {
  // If "user" is ever undefined, this line throws
  return <span>{user.name.toUpperCase()}</span>;
}

Building an Error Boundary

An error boundary must currently be a class component, because it relies on two lifecycle methods that do not have Hook equivalents: static getDerivedStateFromError(), which updates state so the next render shows a fallback UI, and componentDidCatch(), which is typically used for logging.

import { Component } from 'react';

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

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

  componentDidCatch(error, errorInfo) {
    // Log the error to a reporting service
    console.error('ErrorBoundary caught:', error, errorInfo);
  }

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

    return this.props.children;
  }
}

export default ErrorBoundary;

Before error: renders this.props.children normally
After error: getDerivedStateFromError sets hasError = true
Next render: shows "Something went wrong. Please try again later."

Wrapping Parts of the App

Rather than wrapping your entire app in a single error boundary, it is often better to wrap individual risky or independent sections separately. That way, if the "Comments" widget crashes, the rest of the page — the article, the sidebar, the header — keeps working normally.

import ErrorBoundary from './ErrorBoundary';
import Sidebar from './Sidebar';
import ActivityFeed from './ActivityFeed';
import Comments from './Comments';

function Dashboard() {
  return (
    <div className="dashboard">
      <Sidebar />

      <ErrorBoundary>
        <ActivityFeed />
      </ErrorBoundary>

      <ErrorBoundary>
        <Comments />
      </ErrorBoundary>
    </div>
  );
}

export default Dashboard;

What Error Boundaries Do Not Catch

Error boundaries only catch errors thrown during rendering, in lifecycle methods, and in constructors of the components below them. They intentionally do not catch every kind of error in your app.

The react-error-boundary Library

Writing the same class boundary by hand in every project gets repetitive. The popular react-error-boundary package provides a ready-made <ErrorBoundary> component with a friendlier API, including a "resetKeys" option to automatically recover once the underlying data changes.

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

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

function App() {
  return (
    <ErrorBoundary FallbackComponent={Fallback}>
      <Comments />
    </ErrorBoundary>
  );
}

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Error boundaries are React's built-in safety net for rendering errors, letting a single broken section fail gracefully instead of crashing the whole application. Understanding their limitations — no event handlers, no async code — is just as important as knowing how to build one.

In this lesson, you learned why uncaught render errors crash React apps, how to build a class-based error boundary, how to isolate failures by wrapping specific sections, and what error boundaries cannot catch. Next, you will learn how portals let you render content outside your component's normal DOM position.