/web-error-handling-error-boundaries

name: web-error-handling-error-boundaries
description: Error boundary patterns, fallback UI, reset/retry, react-error-boundary library, React 19 createRoot error hooks

React Error Boundaries

> **Quick Guide:** A boundary catches errors thrown during render, in lifecycle methods and in constructors, and swaps the subtree for fallback UI. It never sees event-handler, async or server-render errors — those reach it only when something calls `showBoundary()`. Boundaries are class components, because `getDerivedStateFromError` and `componentDidCatch` have no hook equivalent. React 19 adds `onCaughtError`, `onUncaughtError` and `onRecoverableError` on `createRoot`, which log rather than render and are silently ignored on React 18.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — the class boundary, `react-error-boundary` usage, `resetKeys`, `useErrorBoundary`, granular placement
• [examples/react-19-hooks.md](examples/react-19-hooks.md) — `createRoot`/`hydrateRoot` error options, `captureOwnerStack()`, error filtering
• [examples/recovery.md](examples/recovery.md) — retry limits, exponential backoff, error classification
• [examples/testing.md](examples/testing.md) — what makes a boundary testable, and the fixtures that do it
• [reference.md](reference.md) — what boundaries catch, lifecycle and prop tables, checklists

---

Which path applies

• **No boundary dependency wanted** — write the class yourself; `getDerivedStateFromError` plus

`componentDidCatch` is the whole API, and [examples/core.md](examples/core.md) has it in full.

• **`react-error-boundary` is available** — take `resetKeys`, `useErrorBoundary` and the

`FallbackProps` type rather than reimplementing them, and follow [examples/core.md](examples/core.md).

• **React 19, and the question is logging rather than UI** — the three `createRoot` options report

every error including the ones no boundary caught; see [examples/react-19-hooks.md](examples/react-19-hooks.md).

---

<critical_requirements>

Before writing error boundary code

**Return new state from `getDerivedStateFromError` and put every side effect in `componentDidCatch`.** The first runs during render, where a fetch or a log call breaks React's phase rules; the second runs at commit, where they are safe.

**Wrap each feature area in its own boundary as well as the root.** A single root boundary turns one failing widget into a blank page, and the fallback can say what failed only when it sits beside the thing that failed.

**Give the fallback a way back — a reset callback, `resetKeys`, or both.** Without one the only recovery a user has is a full page reload, which costs them everything they had typed.

**Put `role="alert"` on the fallback and make its controls real buttons.** The subtree vanishing is silent otherwise, and a screen reader user gets no announcement that anything went wrong.

**Route async and event-handler failures through `showBoundary()`.** A boundary cannot see a rejected promise, so an unhandled one leaves the UI showing stale content with no error state at all.

</critical_requirements>

---

**Auto-detection:** error boundary, ErrorBoundary, getDerivedStateFromError, componentDidCatch, fallback UI, react-error-boundary, useErrorBoundary, showBoundary, error fallback, onCaughtError, onUncaughtError, onRecoverableError, captureOwnerStack, FallbackProps, resetKeys

**Applies to:**

• Catching render-phase errors and showing fallback UI in their place
• Reset and retry after a caught error, including retry limits and backoff
• Deciding where boundaries go and how coarse each one should be
• Centralised error reporting from the React root

**Handled elsewhere:**

• Errors thrown in server rendering — the rendering framework decides what a failed render sends to the client, and no client boundary is mounted yet.
• Request failures in a data layer — a boundary sees them only if something rethrows or calls `showBoundary()`; retry and cache invalidation belong to whatever fetches.
• Field-level validation feedback — an invalid form field is expected input, so it renders inline rather than replacing the subtree.
• The monitoring destination — `onError` and the root handlers hand you an error and a component stack, and where those go is the reporting tool's concern.

---

<philosophy>

Philosophy

A render error that no boundary catches unmounts the entire tree: React tears the root down rather than leave a half-rendered document on screen, so one thrown error anywhere becomes a blank page.

A boundary buys **isolation** against that: the blast radius is the subtree the nearest boundary wraps, so where the boundaries sit decides how much of the page a single bug costs. That makes placement the real decision — recovery, fallback wording and logging all follow from it.

Boundaries do not replace `try`/`catch`; they cover the one region `try`/`catch` cannot reach, which is React's own render.

</philosophy>

---

<patterns>

Core patterns

Pattern 1: Class-based boundary

The two lifecycle methods split by phase: `getDerivedStateFromError` is pure and returns state, `componentDidCatch` is where reporting goes.

static getDerivedStateFromError(error: Error): State {
  return { hasError: true, error };
}

componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
  this.props.onError?.(error, errorInfo);
}

Full code: [examples/core.md](examples/core.md)

Pattern 2: `react-error-boundary`

A `FallbackComponent` receives `error` and `resetErrorBoundary`, so the retry control lives wherever the design wants it. `onError` keeps reporting out of the fallback.

<ErrorBoundary FallbackComponent={ErrorFallback} onError={report}>
  <Dashboard />
</ErrorBoundary>;

function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div role="alert">
      <p>{error.message}</p>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

The