Error Boundaries

In one minute

If a component throws while rendering and nothing catches it, React removes the whole app from the page. You can’t fix that with try/catch around JSX, because JSX only creates element objects: the component runs later, inside React. An error boundary is a component that catches errors thrown while rendering anything below it and shows a fallback instead, like a catch block for a part of the tree. Most apps use the small react-error-boundary package rather than writing the class component themselves.

You’ll be able to: put boundaries in the right place, know which errors they can’t see, and recover with “Try again”.

1function ProductDetails({ product }) {2  return <p>{formatUSD(product.price.cents)}</p>3}45<main>6  <h1>Store</h1>7  <ProductDetails product={mysteryBox} />8</main>

1function ProductDetails({ product }) {2  return <p>{formatUSD(product.price.cents)}</p>3}45<main>6  <h1>Store</h1>7  <ErrorBoundary FallbackComponent={ErrorFallback}>8    <ProductDetails product={mysteryBox} />9  </ErrorBoundary>10  <ProductDetails product={mug} />11</main>

The example: a product the API sent without a price

function ProductDetails({ product }: { product: MaybeProduct }) {
	log(`ProductDetails renders ${product.id}`)
	return (
		<article className="product-card">
			<h2>{product.name}</h2>
			<p className="price">{formatUSD(product.price!.cents)}</p>
		</article>
	)
}

Without a boundary

r.render(
	<main>
		<h1>Store</h1>
		<ProductDetails product={broken} />
	</main>,
)

What the lesson logged (the root was created with onUncaughtError / onCaughtError callbacks):

ProductDetails renders p404
ProductDetails renders p404
root: uncaught → Cannot read properties of undefined (reading 'cents')

And #root afterwards:

Empty: the heading and everything else is gone. Notice ProductDetails renders p404 twice: when a component throws, React renders it once more before giving up, in case the error was a one-off.

With a boundary

function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
	return (
		<div role="alert">
			<p>Couldn’t show this product: {(error as Error).message}</p>
			<button onClick={resetErrorBoundary}>Try again</button>
		</div>
	)
}

r.render(
	<main>
		<h1>Store</h1>
		<ErrorBoundary FallbackComponent={ErrorFallback}>
			<ProductDetails product={broken} />
		</ErrorBoundary>
		<ProductDetails product={fine} />
	</main>,
)

The page text afterwards:

[
  "Store",
  "Couldn’t show this product: Cannot read properties of undefined (reading 'cents')",
  "Try again",
  "Ceramic Mug",
  "$18.00"
]

Only the broken product was replaced. The heading and the healthy product next to it are still there.

What a boundary can’t catch

A boundary catches errors thrown while React renders (and in lifecycle methods). It can’t see errors that happen outside rendering: event handlers, setTimeout, promises. For those, useErrorBoundary().showBoundary(error) hands the error to the nearest boundary yourself:

function AddToCart() {
	const { showBoundary } = useErrorBoundary()
	return (
		<>
			<button id="unsafe" onClick={() => { throw new Error('Cart service is down') }}>
				Add to cart
			</button>
			<button id="safe" onClick={() => {
				try {
					throw new Error('Cart service is down')
				} catch (error) {
					showBoundary(error)
				}
			}}>
				Add to cart (reported)
			</button>
		</>
	)
}

Clicking “Add to cart”:

{
  "logs": [
    "window error event → Uncaught Error: Cart service is down"
  ],
  "warnings": [],
  "fallbackShown": false
}

Clicking “Add to cart (reported)”:

{
  "logs": [
    "root: caught by a boundary → Cart service is down"
  ],
  "warnings": [],
  "fallbackShown": true,
  "text": [
    "Couldn’t show this product: Cart service is down",
    "Try again"
  ]
}

A boundary also can’t catch an error in itself or in its fallback: those go to the next boundary up.

Trying again

resetErrorBoundary (passed to the fallback) clears the error and mounts the children again from scratch. Pair it with onReset to fix whatever caused the error:

function Page() {
	const [product, setProduct] = useState(broken)
	return (
		<ErrorBoundary FallbackComponent={ErrorFallback} onReset={() => setProduct(fine)}>
			<Note />
			<ProductDetails product={product} />
		</ErrorBoundary>
	)
}

{
  "logs": [
    "ProductDetails renders p404",
    "ProductDetails renders p404",
    "root: caught by a boundary → Cannot read properties of undefined (reading 'cents')",
    "ProductDetails renders p1"
  ],
  "warnings": [],
  "before": [
    "Couldn’t show this product: Cannot read properties of undefined (reading 'cents')",
    "Try again"
  ],
  "after": [
    "Ceramic Mug",
    "$18.00"
  ]
}

The note input was inside the boundary, so it disappeared with the error and came back empty: a reset re-mounts, it doesn’t restore state.

Where to put boundaries

• The component that may throw must be a child of the boundary, not the component that renders the boundary. A boundary only catches errors from the tree below it.
• One boundary near the root avoids blank pages; smaller ones around independent widgets (a product, a review list, a sidebar) keep the rest of the page usable.
• Still log everything: React 19’s createRoot(container, { onCaughtError, onUncaughtError }) runs for every error, caught or not.

Interview Q&A

Related

• Forms: errors thrown in event handlers and actions.
• Rendering Arrays: another way to remount a subtree, with key.

Sources

• react.dev: Catching rendering errors with an error boundary, createRoot options
• react-error-boundary
• Topic order inspired by Kent C. Dodds’ EpicReact React Fundamentals workshop; the example app and code here are this handbook’s own.

Primary source: react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary