# Error Boundaries & Resilience

> Isolate render failures so one widget can't crash the page.

Frontend architecture guidance from fearchitect, written by Abas Turabli and last reviewed 2026-06-21. Source: https://fearchitect.com/topics/error-boundaries-resilience

Use it as reference for the task at hand. Before changing code, check this guidance against the codebase: where the code already makes a different, deliberate choice, flag the conflict instead of rewriting it. Library APIs move faster than this guide, so confirm exact signatures in the official docs linked at the end.

## Summary

An error boundary catches thrown values during rendering, lifecycle methods, and child constructors — then shows a fallback instead of unmounting the whole tree. Placement granularity determines blast radius: per-route boundaries limit a crash to one page, per-widget boundaries keep the rest of the UI alive. Next.js App Router formalises this with `error.tsx` and `global-error.tsx`.

## Error boundary

A React component that catches errors thrown by its subtree during rendering, lifecycle methods, and constructors — then renders a fallback UI instead of propagating the crash upward. Without one, any unhandled render error unmounts the entire React tree from the root. Boundaries contain the blast to a subtree, keeping the rest of the page functional. The `react-error-boundary` package wraps the class-component API in a declarative `<ErrorBoundary fallback={…}>` that works inside function components.

## What error boundaries do NOT catch

- Event handlers — errors inside onClick/onChange need try/catch; they don't propagate through React's render path.
- Async code — setTimeout callbacks and Promise rejections happen outside the render cycle; use `useErrorBoundary` to rethrow them.
- SSR — boundaries only activate in the browser; server render errors go to the server framework.
- The boundary itself — an error thrown in the boundary's own render escapes to the next boundary up the tree.

## Per-route boundary with Next.js App Router `error.tsx`

Next.js generates a client-side error boundary from any `error.tsx` file in the `app/` directory. The file receives `error` and `reset` as props.

**app/dashboard/error.tsx**

```tsx
"use client"; // error.tsx must be a Client Component

import { useEffect } from "react";

interface Props {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function DashboardError({ error, reset }: Props) {
  useEffect(() => {
    // Send to your error-reporting service
    console.error("[dashboard] render error", error.digest, error);
  }, [error]);

  return (
    <div role="alert">
      <p>The dashboard failed to load.</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}
```

`reset()` re-renders the route segment from scratch. `error.digest` is a server-generated hash that correlates the client error with the server log entry.

## Per-widget boundary with `react-error-boundary` and reset keys

Use `resetKeys` to automatically retry when a dependency (e.g. a query key) changes after the user takes action.

**components/RecommendationsPanel.tsx**

```tsx
import { ErrorBoundary } from "react-error-boundary";

function PanelFallback({
  error,
  resetErrorBoundary,
}: {
  error: Error;
  resetErrorBoundary: () => void;
}) {
  return (
    <aside role="alert">
      <p>Recommendations unavailable.</p>
      <button onClick={resetErrorBoundary}>Retry</button>
    </aside>
  );
}

export function RecommendationsPanel({ userId }: { userId: string }) {
  return (
    <ErrorBoundary
      FallbackComponent={PanelFallback}
      resetKeys={[userId]}        // resets boundary when userId changes
      onError={(err, info) => {
        reportError(err, info.componentStack);
      }}
    >
      <RecommendationsList userId={userId} />
    </ErrorBoundary>
  );
}
```

`resetKeys={[userId]}` clears the error state on navigation to a new user profile — no manual reset button needed in that scenario.

## Watch out: SSR + `global-error.tsx` must own the document shell

Next.js `global-error.tsx` replaces the root layout when it fires, so the layout's `<html>` and `<body>` are gone. The `global-error.tsx` file must render its own `<html>` and `<body>` or the page will be malformed. This catches errors in the root layout itself — errors inside route segments go to the nearest `error.tsx` instead.

## Key terms

- **error boundary**: A React class component implementing `getDerivedStateFromError` or `componentDidCatch` that catches render-phase errors in its subtree.
- **react-error-boundary**: Third-party package wrapping the class-based API into `<ErrorBoundary>` and `useErrorBoundary` hook for function component authoring.
- **resetKeys**: Props on `react-error-boundary`'s `<ErrorBoundary>` that reset the error state when their values change, enabling automatic retry.
- **error.tsx**: Next.js App Router file that becomes the error boundary for its route segment, receiving `error` and `reset` props.
- **global-error.tsx**: Next.js App Router file at the root that catches errors in the root layout; must include `<html>` and `<body>` tags.

## Related topics

- [Frontend Testing Strategy](https://fearchitect.com/topics/frontend-testing.md): Test what the user sees, not how the code is wired.
- [Frontend Observability](https://fearchitect.com/topics/frontend-observability.md): Capture errors, measure real-user performance, and trace what breaks in production.
- [Rendering Strategies: CSR / SSR / SSG / ISR](https://fearchitect.com/topics/rendering-strategies.md): Where and when HTML is generated: build, request, browser, or revalidated.
- [React Server Components](https://fearchitect.com/topics/react-server-components.md): Server-rendered components that ship zero JS to the browser.
- [Deployment Strategies & Feature Flags](https://fearchitect.com/topics/deployment-strategies-feature-flags.md): Decouple deploy from release using blue-green, canary, and flags.
- [State Machines](https://fearchitect.com/topics/state-machines.md): Model UI as explicit states with typed transitions to kill impossible states.

## Further reading

- [React — Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
- [react-error-boundary — npm](https://github.com/bvaughn/react-error-boundary)
- [Next.js — error.js convention](https://nextjs.org/docs/app/api-reference/file-conventions/error)
- [Next.js — global-error.js](https://nextjs.org/docs/app/api-reference/file-conventions/error#global-errorjs)