An error boundary in React that never shows its fallback
The whole screen goes blank when a component throwsShort 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.
Fix it fast
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.json2Match what you see, then jump to its fix
- 1
No 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
A 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
- 1
What does the error look like?
The whole screen goes blank when a component throwsThe 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 devConfirmed by react.dev
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.jsx2Fix
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 devConfirmed by react.dev
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:
- 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
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 fixWeb apps
Axios request is not cancelled when a React component unmounts
A cancelled request is logged as an error in the catch block
Axios cancels a request when you pass it an AbortSignal and later call abort() on its controller.
4 causes, each with a fix