“One widget threw an error and the whole page went white. How do you prevent that?” Since React 16, an uncaught render error unmounts the entire root, so a single bad API response in a sidebar can blank a checkout page. Answering well takes three things: knowing what boundaries catch, deciding where to put them, and giving users a way to recover.
Strong answers go beyond “wrap the app in an error boundary”. They describe scope (what should fail together), the errors boundaries cannot see, and a reset strategy that does not require reloading the page. Boundaries are still written as classes (or through a library such as react-error-boundary), so it helps to know basic class components, the render and commit phases and what Suspense boundaries do; React 19 also reports each error once instead of logging duplicates.
What a boundary catches, what it misses, and where it goes
An error boundary is a class component that implements static getDerivedStateFromError (to render a fallback) and usually componentDidCatch (to log). It catches errors thrown while rendering its children, in their lifecycle methods and in their effects, and replaces that subtree with a fallback while the rest of the page keeps working. It does not catch errors in event handlers, in asynchronous code like setTimeout or promise callbacks, during server rendering, or in itself. Place boundaries around regions that are useful on their own, and give each fallback a way to retry, typically by resetting the boundary when the relevant data changes.
How React routes a render error to the nearest boundary
import { Component } from 'react';
class ErrorBoundary extends Component {
state = { error: null };
static getDerivedStateFromError(error) {
return { error };
}
componentDidCatch(error, info) {
reportError(error, info.componentStack);
}
render() {
if (this.state.error) {
return this.props.fallback({
error: this.state.error,
reset: () => this.setState({ error: null }),
});
}
return this.props.children;
}
}When a descendant throws during render, React walks up the tree to the nearest boundary, calls getDerivedStateFromError during rendering to compute the fallback state, renders the fallback, then calls componentDidCatch after commit with a component stack. Everything outside the boundary stays mounted and interactive.
Errors in event handlers do not happen during rendering, so React does not route them to boundaries. Handle them with try/catch and state, or rethrow them into render deliberately:
const [error, setError] = useState(null);
if (error) throw error; // now a boundary can catch it
async function onSave() {
try { await save(); } catch (e) { setError(e); }
}Rejected promises read with use() inside Suspense are thrown during render, so boundaries do catch those.
A banking dashboard blanked by one bad transaction
Picture a banking dashboard with one boundary at the root. A malformed transaction from a partner API (a missing amount field) makes amount.toFixed(2) throw inside a “Recent activity” widget. Customers see a full-page “Something went wrong” screen and cannot reach their balance or transfers, even though only one list failed.
Three changes contain it. First, each dashboard widget gets its own boundary with a compact fallback and a retry button. Second, the boundary around “Recent activity” is keyed on the selected account, so switching accounts clears the error. Third, the logging in componentDidCatch includes the component stack and the account type, which points straight at the widget and the kind of account whose data is malformed.
<ErrorBoundary key={accountId} fallback={({ reset }) => (
<Card>
<p>Recent activity is unavailable right now.</p>
<button onClick={reset}>Try again</button>
</Card>
)}>
<RecentActivity accountId={accountId} />
</ErrorBoundary>When the next bad record arrives, only that card shows an error; balances and transfers keep working. The root boundary stays for failures nobody anticipated.
The root cause still needs a fix: check the partner response in the function that fetches transactions (reject or skip a record without a numeric amount), because boundaries contain failures but do not prevent them.
Placing boundaries by blast radius
Step 1: Decide what should fail together
Map the page into regions that are useful on their own. On a dashboard, each widget is independent; in a checkout, the order summary and payment form depend on each other and should fail together. A boundary’s scope equals the blast radius of a failure.
Step 2: Add a root boundary as a last resort
A top-level boundary prevents a blank screen and offers a reload or a link home. It is necessary but not sufficient, because everything below it is lost when it triggers.
Step 3: Add region boundaries with useful fallbacks
<ErrorBoundary fallback={({ reset }) => (
<WidgetError message="Revenue chart could not load" onRetry={reset} />
)}>
<Suspense fallback={<ChartSkeleton />}>
<RevenueChart range={range} />
</Suspense>
</ErrorBoundary>Pair each data-loading Suspense boundary with an error boundary at the same level, so every region has a loading state and a failure state with the same footprint.
Step 4: Reset when the cause changes
A retry button that resets the boundary will re-render the same children with the same props; if the data is still broken, it fails again. Reset also when the inputs change. The simplest way is a key:
<ErrorBoundary key={range} fallback={...}>
<RevenueChart range={range} />
</ErrorBoundary>Changing the range remounts the boundary, clearing the error. The reset with key note explains the mechanism. Libraries like react-error-boundary offer resetKeys for the same purpose.
Too few boundaries, too many, and retries that change nothing
- “Error boundaries catch all errors.” Not event handlers, not async callbacks, not server rendering, not errors in the boundary itself.
- Only a root boundary. One bad widget takes down the whole page.
- A boundary around every component. Fallbacks everywhere make a page look broken in a dozen places and are hard to design.
- A retry that changes nothing. If props and data are the same, the child throws again. Refetch or reset on input changes.
- Swallowing errors without logging. Always report from
componentDidCatchor the rootonCaughtErrorhandler.
Breaking a widget on purpose to test the fallback
Use a component that throws on demand:
function Bomb({ explode }) {
if (explode) throw new Error('boom');
return <p>widget ok</p>;
}
export default function App() {
const [explode, setExplode] = useState(false);
return (
<>
<button onClick={() => setExplode(true)}>break widget</button>
<p>header still works</p>
<ErrorBoundary fallback={({ reset }) => (
<button onClick={() => { setExplode(false); reset(); }}>widget failed, retry</button>
)}>
<Bomb explode={explode} />
</ErrorBoundary>
</>
);
}Clicking “break widget” replaces only the widget with its fallback; the header text remains. Clicking retry restores the widget. The retry handler needs both calls: reset() alone re-renders Bomb with explode still true, so it throws again, and setExplode(false) alone leaves the boundary holding its error. In React 18 development builds a caught error is also rethrown to window, so an overlay such as Create React App’s appears even though the boundary handled it; React 19 reports caught errors through console.error instead. In a test, use React Testing Library and assert that the fallback appears and the sibling text is still present.
Classes, Suspense, React 19 root options and Next.js
Why are error boundaries still classes? There is no hook equivalent of getDerivedStateFromError yet. Most teams use react-error-boundary, which wraps a class and exposes a function-component API.
How do error boundaries relate to Suspense? Suspense handles “not ready”, error boundaries handle “failed”. A rejected promise in a Suspense-enabled read is thrown and caught by the nearest error boundary.
What do onCaughtError and onUncaughtError do in React 19? They are root options for centralised reporting: one fires for errors caught by a boundary, the other for errors that reached the root. onRecoverableError covers errors React recovered from automatically, such as hydration mismatches.
Do frameworks provide boundaries? Yes. In the Next.js App Router, an error.js file creates an error boundary around a route segment, which is the same idea with routing built in.
Interview question: a rejected save the boundary never sees
A form’s submit handler calls await api.save() and the API sometimes rejects. The team wrapped the form in an error boundary, but failures still produce an unhandled promise rejection and no fallback. Explain why, and give two ways to show an error state.
A complete answer
The rejection happens in an async event handler, outside rendering, so React never routes it to the boundary; it surfaces as an unhandled promise rejection. Option one, usually best for forms: catch it locally with try/catch, store the message in state, and render an inline error near the submit button while keeping the user’s input. Option two, when the failure should replace the region: store the error in state and throw it during the next render (if (error) throw error), which the boundary then catches. In React 19, using a form action with useActionState is another option: return an error result from the action and render it. See useActionState forms.
Related notes on Suspense, keys and forms
Practise with the React interview questions and the React MCQs. Related notes: Suspense boundaries, resetting with a key and useActionState forms. Official reference: Catching rendering errors with an error boundary in the Component reference on react.dev.