BACK TO BLOG

React error boundaries

Mobile Developer
March 27, 2025
Updated on April 3, 2025
0 MIN READ
#next-js#ssg#react#error

Introduction

React applications, like any complex software, can encounter runtime errors during execution. These errors might stem from API failures, unexpected data formats, or simple programming mistakes. Without proper handling, such errors can crash your entire application, leading to poor user experiences. This is where React Error Boundaries come into play—a powerful feature that helps you gracefully handle JavaScript errors in your component tree.

Introduced in React 16, 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 crashing the whole application. In this post, we'll explore how Error Boundaries work, how to implement them effectively, and best practices for using them in production applications.

What Are React Error Boundaries?

Error Boundaries are React components that implement either or both of the following lifecycle methods:

  1. static getDerivedStateFromError(): This method is used to render a fallback UI after an error has been thrown.
  2. componentDidCatch(): This method is used for logging error information.

Here's the key thing to understand: Error Boundaries only catch errors that occur:

  • During rendering
  • In lifecycle methods
  • In constructors of the whole tree below them

They do NOT catch errors for:

  • Event handlers (use regular try/catch for these)
  • Asynchronous code (e.g., setTimeout or requestAnimationFrame callbacks)
  • Server-side rendering
  • Errors thrown in the Error Boundary itself (only its children)

Here's a basic example of an Error Boundary component:

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) {
    // You can log the error to an error reporting service
    console.error('Error caught by Error Boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      // You can render any custom fallback UI
      return <h1>Something went wrong.</h1>;
    }

    return this.props.children;
  }
}

Implementing Error Boundaries in Your Application

Now that we understand what Error Boundaries are, let's look at how to implement them effectively in a React application.

1. Wrapping Components Strategically

You don't need to wrap every single component with an Error Boundary. Instead, think about logical places in your component hierarchy where errors might occur and where you'd want to isolate failures. Some good candidates include:

  • Top-level route components
  • Complex widget components
  • Sections of your app that can function independently

Here's an example of how you might structure this:

function App() {
  return (
    <ErrorBoundary>
      <Header />
      <ErrorBoundary>
        <MainContent />
      </ErrorBoundary>
      <Footer />
    </ErrorBoundary>
  );
}

2. Creating Specialized Error Boundaries

You can create different Error Boundaries for different parts of your application, each with their own fallback UI and error handling logic. For example:

class UserProfileErrorBoundary extends React.Component {
  // ... same methods as before

  render() {
    if (this.state.hasError) {
      return (
        <div className="profile-error">
          <h2>Profile Unavailable</h2>
          <p>We couldn't load the user profile.</p>
          <button onClick={() => window.location.reload()}>Try Again</button>
        </div>
      );
    }

    return this.props.children;
  }
}

3. Error Recovery Strategies

Beyond just showing a fallback UI, you might want to implement recovery strategies. Here are a few approaches:

  1. Retry Mechanism: Provide a button to retry the failed operation
  2. Alternative Content: Show simplified content when the rich version fails
  3. Feature Flags: Disable problematic features gracefully

Here's an example with a retry button:

class RetryErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, errorCount: 0 };
  }

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

  componentDidCatch(error, errorInfo) {
    console.error(error, errorInfo);
    this.setState(prev => ({ errorCount: prev.errorCount + 1 }));
  }

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

  render() {
    if (this.state.hasError) {
      return (
        <div>
          <p>Something went wrong.</p>
          {this.state.errorCount < 3 && (
            <button onClick={this.handleRetry}>Retry</button>
          )}
        </div>
      );
    }

    return this.props.children;
  }
}

Best Practices for Error Boundaries

To get the most out of Error Boundaries in your React applications, consider these best practices:

1. Use Error Boundaries Sparingly

While it might be tempting to wrap every component in an Error Boundary, this can lead to:

  • Performance overhead
  • Difficult-to-debug error swallowing
  • Confusing user experiences with partial failures

Instead, focus on strategic placement where errors are most likely or most critical to handle.

2. Log Errors to a Monitoring Service

The componentDidCatch method is the perfect place to integrate with error monitoring services like Sentry, Rollbar, or Bugsnag:

componentDidCatch(error, errorInfo) {
  // Example with Sentry
  Sentry.captureException(error, { extra: errorInfo });
  
  // Or your custom logging
  logErrorToService(error, errorInfo.componentStack);
}

3. Consider Server-Side Rendering

Error Boundaries don't catch errors during server-side rendering. For Next.js or other SSR frameworks, you'll need additional error handling at the server level.

4. Test Your Error Boundaries

Just like any other code, you should test your Error Boundaries. You can create test components that deliberately throw errors to verify your Error Boundary behavior:

function BuggyComponent() {
  throw new Error('Test error');
  return <div>This won't render</div>;
}

// In your test
<ErrorBoundary>
  <BuggyComponent />
</ErrorBoundary>

5. Provide Helpful Fallback UIs

Your fallback UI should:

  • Clearly communicate that an error occurred
  • Provide guidance on what to do next
  • Match your application's design language
  • Avoid technical jargon that might confuse users

Conclusion

React Error Boundaries are a powerful tool for building resilient applications that can gracefully handle runtime errors. By strategically implementing Error Boundaries throughout your component tree, you can prevent entire application crashes and provide better user experiences when things go wrong.

Remember that Error Boundaries are just one part of a comprehensive error handling strategy. Combine them with proper error logging, monitoring, and recovery mechanisms to build truly robust React applications.

As you implement Error Boundaries in your projects, keep in mind the best practices we've discussed: strategic placement, proper error logging, thoughtful fallback UIs, and thorough testing. With these techniques, you'll be well-equipped to handle errors gracefully in your React applications.

Share this article

MORE ARTICLES