Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

An error boundary in React that never shows its fallback

ErrorThe whole screen goes blank when a component throws

Short answer

Error boundaries must be class components; React has no function-component version. A boundary also skips errors from event handlers, async code such as setTimeout, server rendering, and errors thrown in the boundary itself. Use a class (or the react-error-boundary package) above the failing tree, and handle the other cases with try/catch.

  • Applies to React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Note where the error is thrown: while rendering, or inside an event handler or timer. Boundaries only see render errors from their children.

    grep -rn 'getDerivedStateFromError\|react-error-boundary' src/ package.json
  2. 2Match what you see, then jump to its fix

    1. 1No component in the tree defines getDerivedStateFromError or componentDidCatch, and the page goes blank on a render errorThere is no class-based boundary above the failing componentFix
    2. 2A boundary exists, but the error comes from an onClick, a setTimeout, a promise callback, or from the boundary's own renderThe error is thrown where boundaries do not lookFix

What does the error look like?

  • The whole screen goes blank when a component throws
  • The boundary fallback does not show when an error is thrown in an onClick or setTimeout callback

Cause 1 of 2

There is no class-based boundary above the failing component

1Check

React docs state there is no way to write an error boundary as a function component. A function that only returns children is not a boundary.

grep -rn 'componentDidCatch\|getDerivedStateFromError' src/

2Fix

Add a class boundary, or install the react-error-boundary package (npm install react-error-boundary) and use its ErrorBoundary component.

import * as React from 'react';

class ErrorBoundary extends React.Component {
  state = { hasError: false };

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

  componentDidCatch(error, info) {
    console.error(error, info.componentStack);
  }

  render() {
    return this.state.hasError ? this.props.fallback : this.props.children;
  }
}

// usage
<ErrorBoundary fallback={<p>Something went wrong</p>}>
  <Profile />
</ErrorBoundary>

3Verify

Make Profile throw during render. The fallback text replaces it, and the rest of the page stays.

npm run dev

Confirmed by react.dev

Did this fix it?

Cause 2 of 2

The error is thrown where boundaries do not look

1Check

Boundaries do not catch errors in event handlers, asynchronous code such as setTimeout or requestAnimationFrame callbacks, server-side rendering, or errors thrown by the boundary itself.

grep -n 'setTimeout\|onClick\|await ' src/components/Profile.jsx

2Fix

Catch those errors where they happen with try/catch, and show the result through state. Put a second boundary above the first if the boundary's own render can throw.

function SaveButton() {
  const [error, setError] = React.useState(null);

  async function handleClick() {
    try {
      await save();
    } catch (e) {
      setError(e);
    }
  }

  if (error) return <p>Could not save.</p>;
  return <button onClick={handleClick}>Save</button>;
}

3Verify

Force save() to reject. The message shows instead of an unhandled error.

npm run dev

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Put one boundary near the root and smaller ones around parts that can fail on their own, such as a widget fed by an API.
  • Send componentDidCatch details to your logging service so you hear about failures.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.