Maaz Zindani

Loading the index…

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

React logs 'Consider adding an error boundary to your tree' and the page goes blank

ErrorConsider adding an error boundary to your tree to customize error handling behavior.

Short answer

React prints this development message when a component throws while rendering and no error boundary is above it. The message is a hint, not the error. React then removes the whole UI from the screen. Read the real error and its component stack, fix the throwing component, and add a boundary around the part of the tree that may fail.

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

Fix it fast

  1. 1Find out which cause you have

    Log the error together with its component stack, so you see which component threw and why. Pass the handler when you create the root.

    import { createRoot } from 'react-dom/client';
    
    const root = createRoot(document.getElementById('root'), {
      onUncaughtError: (error, errorInfo) => {
        console.error(error, errorInfo.componentStack);
      },
    });
  2. 2Match what you see, then jump to its fix

    1. 1The warning comes right after an ordinary error, such as a TypeError, and the screen turns blankA component throws while rendering, and the thrown error is the real problemFix
    2. 2One failing widget empties the whole page, not only the widgetThere is no error boundary around the part of the tree that can failFix
    3. 3The warning still appears although an ErrorBoundary is in the codeA boundary exists, but it sits below the failing component or fails itselfFix

What does the error look like?

  • Consider adding an error boundary to your tree to customize error handling behavior.
  • Visit https://react.dev/link/error-boundaries to learn more about error boundaries.

Cause 1 of 3

A component throws while rendering, and the thrown error is the real problem

1Check

React shows the warning only for an error that nothing caught. The error itself is logged next to it. In production builds React does not print this message at all, only the raw error.

# the first lines of the console, and the component stack from the handler above
grep -rn "onUncaughtError" src

2Fix

Fix the error that the stack points at. For example, when a component maps over data that is still undefined, give that value a safe default.

function OrderList({ orders = [] }) {
  return orders.map((o) => <li key={o.id}>{o.name}</li>);
}

3Verify

Reload the page. The error and the warning no longer appear and the UI stays on screen.

# browser DevTools > Console

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

There is no error boundary around the part of the tree that can fail

1Check

Without a boundary, a rendering error makes React remove the entire UI from the screen. A boundary lets a fallback take the place of only the part that crashed.

grep -rn "getDerivedStateFromError\|react-error-boundary" src package.json

2Fix

Write an error boundary, or use the react-error-boundary package, and wrap the risky section with a fallback. A boundary has to be a class component with getDerivedStateFromError.

import { Component } from 'react';

class ErrorBoundary extends Component {
  constructor(props) {
    super(props);
    this.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;
  }
}

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

3Verify

Trigger the error again. The fallback shows in place of Profile and the rest of the page stays.

# browser: reload and reproduce the failing action

Confirmed by react.dev

Did this fix it?

Cause 3 of 3

A boundary exists, but it sits below the failing component or fails itself

1Check

A boundary catches errors from the components inside it. It does not catch an error thrown by the boundary itself, and it does not catch errors from event handlers, server-side rendering or async code such as setTimeout.

grep -rn "<ErrorBoundary" src

2Fix

Move the boundary above the component that throws, keep its own render simple, and handle event-handler and async errors with try/catch.

<ErrorBoundary fallback={<p>Something went wrong</p>}>
  <Dashboard />   {/* the boundary wraps the component that throws */}
</ErrorBoundary>

3Verify

The fallback replaces the failing section, and the console shows the error as caught, not as uncaught.

# browser DevTools > Console after reproducing the failure

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 load outside data, so one failure stays local.
  • In React 19, report errors with the onCaughtError and onUncaughtError options of createRoot; uncaught errors are no longer re-thrown, so code that relied on that must use these options.
  • Give state that holds a list or an object a safe default, so the first render never meets undefined.

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.