Error Handling

When a component throws while rendering, React can't produce a consistent UI for that part of the tree, so it removes it. Without anything to stop it, the error unwinds all the way up and React unmounts the entire app — the user gets a blank page. An error boundary is a component that stops that unwinding: it catches errors thrown while rendering anything below it, and renders a fallback UI instead.

From my notes: error boundaries "catch errors that occur during rendering, in lifecycle methods, and in the constructors of child components", and they "help prevent the entire application from crashing by isolating where the error occurred and rendering a fallback UI, such as an error message."

The mental model is a circuit breaker in a fuse box. A fault in one room trips that room's breaker; the lights stay on in the rest of the house. Where you put breakers decides how much goes dark: one at the root (the whole app shows "Something went wrong"), one per route, or one per widget (only the broken chart disappears).

There is still no hook for this in React 19.3: an error boundary must be a class component that defines static getDerivedStateFromError (and usually componentDidCatch). In practice most apps use react-error-boundary, which is that class, written once.

import { Component, useState } from "react";

export class ErrorBoundary extends Component {
  state = { error: null };

  // Render phase: turn the error into state. Must be pure.
  static getDerivedStateFromError(error) {
    return { error };
  }

  // Commit phase: side effects such as logging.
  componentDidCatch(error, info) {
    this.props.onError?.(error, info.componentStack);
  }

  render() {
    if (this.state.error) {
      return (
        <div role="alert">
          <p>Something went wrong: {this.state.error.message}</p>
          <button onClick={() => this.setState({ error: null })}>Try again</button>
        </div>
      );
    }
    return this.props.children;
  }
}

export function BuggyCounter() {
  const [count, setCount] = useState(0);
  if (count === 3) throw new Error("I crashed at 3!");
  return <button onClick={() => setCount((c) => c + 1)}>Count: {count}</button>;
}

export function App({ onError }) {
  return (
    <main>
      <ErrorBoundary onError={onError}>
        <BuggyCounter />
      </ErrorBoundary>
      <p>The rest of the page keeps working.</p>
    </main>
  );
}

React 19.3 also logs the caught error once with console.error. In the test, the logged arguments are the error object followed by "The above error occurred in the <BuggyCounter> component." and "React will try to recreate this component tree from scratch using the error boundary you provided, ErrorBoundary." Before React 19, a caught error was logged more than once in development (the error itself was re-thrown and reported as uncaught, plus the "above error" message); React 19 reports each error once. What gets logged, and where, can be changed with the root error callbacks.

getDerivedStateFromError vs componentDidCatch

You need getDerivedStateFromError to show a fallback. A class with only componentDidCatch is still treated as a boundary, but React 19.3 warns in development: "OnlyDidCatch: Error boundaries should implement getDerivedStateFromError(). In that method, return a state update to display an error message or fallback UI." The React 16.0 pattern of calling setState in componentDidCatch to switch the UI is legacy.

Error boundaries vs try/catch

From my notes: "Error boundaries are React's way of handling component rendering failures. While try/catch works for imperative code, error boundaries handle failures that occur during the component lifecycle, which is declarative in React." The clearest way to see why you can't just use try/catch:

function Bomb() {
  throw new Error("render boom");
}

export function Wrapper() {
  try {
    return <Bomb />;
  } catch {
    return <p>caught by try/catch</p>; // never runs
  }
}

try/catch is still the right tool for imperative code you call yourself: inside event handlers, inside effects, around await in async functions (see Handling errors in events and async code).

An error boundary only catches errors that happen while React is rendering or committing the tree below it. Anything that runs at another time, called by someone other than React's render, is outside its reach. From my notes, they do not catch errors in:

• Event handlers (onClick, onSubmit…).
• Asynchronous code (e.g. setTimeout callbacks, fetch promise callbacks).
• Server-side rendering.
• The error boundary itself — "though another error boundary can catch that".

The mental model: a boundary is a try/catch that React wraps around rendering. An event handler runs when the user clicks, long after rendering finished; a timer callback runs from the event loop. Neither is inside React's render, so neither is inside the boundary's try.

export function ClickBomb() {
  return (
    <button
      onClick={() => {
        throw new Error("click boom");
      }}
    >
      Break on click
    </button>
  );
}

export function TimerBomb() {
  return (
    <button
      onClick={() =>
        setTimeout(() => {
          throw new Error("timer boom");
        }, 0)
      }
    >
      Break later
    </button>
  );
}

What they do catch that surprises people

My notes' list is right, but it's worth being precise in the other direction, because several "async-looking" errors are routed to boundaries in React 19:

import { useEffect, useTransition } from "react";

export function EffectBomb() {
  useEffect(() => {
    throw new Error("effect boom");
  }, []);
  return <p>mounted</p>;
}

export function TransitionBomb() {
  const [isPending, startTransition] = useTransition();
  return (
    <button
      disabled={isPending}
      onClick={() =>
        startTransition(async () => {
          await Promise.resolve();
          throw new Error("action boom");
        })
      }
    >
      Save
    </button>
  );
}

Errors in the boundary itself

A boundary can't catch an error thrown by its own render — including its fallback. The error goes to the next boundary up:

import { ErrorBoundary } from "./ErrorBoundary";

class BrokenFallbackBoundary extends ErrorBoundary {
  render() {
    if (this.state.error) throw new Error("fallback boom"); // a bug in the fallback
    return this.props.children;
  }
}

function Bomb() {
  throw new Error("child boom");
}

export function Nested() {
  return (
    <ErrorBoundary>
      <BrokenFallbackBoundary>
        <Bomb />
      </BrokenFallbackBoundary>
    </ErrorBoundary>
  );
}

<ErrorBoundary fallback={<p>Oops</p>}>
  <A /> {/* throws during render */}
  <B /> {/* onClick={() => { throw ... }} */}
  <C /> {/* useEffect(() => { throw ... }, []) */}
  <D /> {/* onClick={() => setTimeout(() => { throw ... })} */}
  <E /> {/* onClick={() => startTransition(async () => { throw ... })} */}
</ErrorBoundary>

Writing the class above in every project gets old, and it's missing features you end up needing: different fallback styles, a reset API, resetting when some value changes, a way to send event-handler errors to the boundary. react-error-boundary (by Brian Vaughn, formerly of the React core team) is that class, done once. My notes: "You can use the popular react-error-boundary library, which provides hooks for using error boundaries in functional components."

A precise version of that sentence: the library still uses a class internally (it has to), but it gives you a ready-made <ErrorBoundary> component, a useErrorBoundary hook to trigger and reset the nearest boundary from function components, and a withErrorBoundary HOC. The installed version is 6.1.6.

From my notes, the full example:

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

// Functional Component
function MyComponent() {
  if (Math.random() > 0.7) {
    throw new Error("Random error!");
  }
  return <h1>Hello from MyComponent!</h1>;
}

// Fallback Component
function ErrorFallback({ error, resetErrorBoundary }) {
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
}

// Usage of ErrorBoundary with a functional component
export function App({ onReset = () => {} }) {
  return (
    <ErrorBoundary
      FallbackComponent={ErrorFallback}
      onReset={() => {
        // Reset the state of the app so the error doesn't happen again
        onReset();
      }}
    >
      <MyComponent />
    </ErrorBoundary>
  );
}

Updates for version 6 (correcting my notes for TypeScript)

The JSX above works unchanged in v6. Two things changed that matter, especially in TypeScript:

• error is typed unknown, not Error (JavaScript lets you throw anything — a string, null, an object). So error.message in a .tsx fallback is a compile error. v6 ships a helper, getErrorMessage(error), that returns the message for Error-like values.
• v6 is ESM-only. Its README says projects whose framework or runtime doesn't support ES modules should stay on version 5.

import { ErrorBoundary, getErrorMessage, type FallbackProps } from "react-error-boundary";

function OldFallback({ error }: FallbackProps) {
  return <pre>{error.message}</pre>; // ❌ 'error' is of type 'unknown'.
}

function Fallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    <div role="alert">
      <pre>{getErrorMessage(error) ?? "Unknown error"}</pre>
      <button onClick={() => resetErrorBoundary()}>Try again</button>
    </div>
  );
}

function UserCard({ id }: { id: number }) {
  if (id < 0) throw new Error(`No user with id ${id}`);
  return <p>User #{id}</p>;
}

export function Profile({ userId, onError }: { userId: number; onError: (e: unknown) => void }) {
  return (
    <ErrorBoundary FallbackComponent={Fallback} onError={(error) => onError(error)} resetKeys={[userId]}>
      <UserCard id={userId} />
    </ErrorBoundary>
  );
}

export { OldFallback };

React 19 lets you decide, once per root, what happens to every error React handles. createRoot and hydrateRoot accept three options:

• onCaughtError(error, info) — an error that an error boundary caught. info has componentStack and errorBoundary (the boundary instance). Default: console.error.
• onUncaughtError(error, info) — an error that no boundary caught, so React unmounted the whole root. Default: window.reportError.
• onRecoverableError(error, info) — an error React recovered from by itself, most commonly a hydration mismatch (it threw away the server HTML and rendered on the client). Default: window.reportError. This one existed in React 18; the other two are new in React 19.

The mental model: these are the root's switchboard. Every error ends up on one of three lines, and you decide where each line rings — the console, your error-monitoring service, an analytics event. Before React 19, the only way to see caught errors centrally was to add logging to every boundary's componentDidCatch, and uncaught errors had to be picked up from window.onerror.

import { createRoot } from "react-dom/client";

export type ErrorKind = "caught" | "uncaught" | "recoverable";
export type Reporter = (kind: ErrorKind, error: unknown, componentStack?: string) => void;

export function createAppRoot(container: Element, report: Reporter) {
  return createRoot(container, {
    onCaughtError(error, info) {
      report("caught", error, info.componentStack);
    },
    onUncaughtError(error, info) {
      report("uncaught", error, info.componentStack);
    },
    onRecoverableError(error, info) {
      report("recoverable", error, info.componentStack);
    },
  });
}

// main.tsx in a real app:
// createAppRoot(document.getElementById("root")!, (kind, error, stack) => monitoring.capture(error, { kind, stack }))
//   .render(<App />);

Because boundaries don't see errors from event handlers and plain async callbacks, those errors need deliberate handling in the handler itself. There are three good options, and choosing between them is a UX decision:

• Handle it locally with try/catch and error state, when the user can do something about it — "Couldn't save, try again" next to the button.
• Forward it to the nearest boundary, when the failure means this whole section can't work. react-error-boundary's showBoundary(error) does that; so does throwing inside a React 19 transition Action.
• Let it escape to a global handler, for logging only — never as your only handling, because the user sees nothing.

The mental model: an error from a click is a message that arrives after the render has finished. Someone has to receive it — the handler (local state), a boundary (by explicit forwarding) or the window (logging). If nobody does, the user just sees a button that silently didn't work.

import { useState } from "react";

export function SaveButton({ save }) {
  const [status, setStatus] = useState("idle"); // "idle" | "saving" | "saved"
  const [error, setError] = useState(null);

  async function handleClick() {
    setStatus("saving");
    setError(null);
    try {
      await save();
      setStatus("saved");
    } catch (e) {
      setError(e instanceof Error ? e.message : String(e));
      setStatus("idle");
    }
  }

  return (
    <div>
      <button onClick={handleClick} disabled={status === "saving"}>
        {status === "saving" ? "Saving…" : "Save"}
      </button>
      {status === "saved" && <p>Saved</p>}
      {error && <p role="alert">Couldn't save: {error}</p>}
    </div>
  );
}

Forwarding an error to a boundary

When a failure means the section can't continue — the data the whole panel needs failed to load — show the boundary's fallback instead of inventing a second error UI. Two ways:

import { useTransition } from "react";
import { ErrorBoundary, useErrorBoundary } from "react-error-boundary";

export function LoadReportButton({ loadReport }) {
  const { showBoundary } = useErrorBoundary();
  return (
    <button
      onClick={() => {
        loadReport().catch((error) => showBoundary(error)); // react-error-boundary
      }}
    >
      Load report
    </button>
  );
}

export function DeleteButton({ remove }) {
  const [isPending, startTransition] = useTransition();
  return (
    <button disabled={isPending} onClick={() => startTransition(async () => await remove())}>
      Delete
    </button>
  );
}

export function Panel({ loadReport, remove }) {
  return (
    <ErrorBoundary fallbackRender={({ error }) => <p role="alert">Panel failed: {error.message}</p>}>
      <LoadReportButton loadReport={loadReport} />
      <DeleteButton remove={remove} />
    </ErrorBoundary>
  );
}

A global safety net for logging

Some errors will always escape: a third-party script, a forgotten .catch. Two window events catch everything that bubbles out, which is ideal for logging:

export function installGlobalErrorLogging(report) {
  const onError = (event) => report("error", event.error ?? event.message);
  const onRejection = (event) => report("unhandledrejection", event.reason);
  window.addEventListener("error", onError);
  window.addEventListener("unhandledrejection", onRejection);
  return () => {
    window.removeEventListener("error", onError);
    window.removeEventListener("unhandledrejection", onRejection);
  };
}