React logs 'Consider adding an error boundary to your tree' and the page goes blank
Consider 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.
Fix it fast
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); }, });2Match what you see, then jump to its fix
- 1
The 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
One failing widget empties the whole page, not only the widgetThere is no error boundary around the part of the tree that can failFix - 3
The warning still appears although an ErrorBoundary is in the codeA boundary exists, but it sits below the failing component or fails itselfFix
- 1
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" src2Fix
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 > ConsoleConfirmed by raw.githubusercontent.com
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.json2Fix
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 actionConfirmed by react.dev
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" src2Fix
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 failureConfirmed by react.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
An error boundary in React that never shows its fallback
The boundary fallback does not show when an error is thrown in an onClick or setTimeout callback
Error boundaries must be class components; React has no function-component version.
2 causes, each with a fixWeb apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fix