Errors outside render: the global net and the React 19 reporting pipeline

The escape paths: where errors actually leave React

A boundary sees only throws during rendering, lifecycles and constructors. Everything else exits through three doors. Event handlers run as plain function calls on the DOM event path, after commit — an uncaught throw there propagates to window as an error event while the committed UI sits untouched: the silently dead Pay button. Effects with async work: the effect body is synchronous and its throw does surface to the boundary — but the moment you put an async function inside (which is the normal data-fetching shape), a rejection becomes a rejected promise, and a rejected promise nobody awaits fires unhandledrejection, never the boundary. Timers and subscriptions: by the time a setTimeout callback or a WebSocket onmessage throws, the render call stack that mounted them is history; React is not even on the stack.

The global net is two listeners, and the distinction between them carries diagnostic weight:

window.addEventListener("error", (e) => {
  report({ kind: "uncaught", error: e.error, stack: e.error?.stack });
});
window.addEventListener("unhandledrejection", (e) => {
  report({ kind: "rejection", error: e.reason }); // often no componentStack, sometimes no stack at all
});

An error event means synchronous code threw and nobody caught it — handlers, timers, third-party scripts. An unhandledrejection means an async chain leaked — a fetch without a catch, an async effect, a fire-and-forget mutation. Neither carries a componentStack, because React was not involved in the catch: you get the JS stack (which function threw), not the component chain (which part of the UI contained it). That asymmetry is why routing errors into boundaries with showBoundary (lesson 01) is more than aesthetics — it upgrades an anonymous global event into a located, fallback-rendering, componentStack-carrying report.

React 19 root options: three severities, built in

React 19 turned error reporting into a first-class root contract. createRoot (and hydrateRoot) accept three callbacks, and they partition every React-visible error by what happened to the user:

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

createRoot(container, {
  onUncaughtError(error, errorInfo) {
    // no boundary caught it — the tree unmounted; the user saw it break
    report({ level: "fatal", error, componentStack: errorInfo.componentStack });
  },
  onCaughtError(error, errorInfo) {
    // a boundary handled it — the user saw a designed fallback
    report({ level: "handled", error, componentStack: errorInfo.componentStack });
  },
  onRecoverableError(error, errorInfo) {
    // React healed on its own — hydration mismatches land here
    report({ level: "recoverable", error: error.cause ?? error, componentStack: errorInfo.componentStack });
  },
}).render(<App />);

Each receives the error plus errorInfo.componentStack. The split is the severity model you previously had to reverse-engineer: onUncaughtError is the white-screen class — page-level alert material. onCaughtError is the handled class — a boundary rendered its fallback, the user kept a working page; track its rate (a spike means a widget is broken at scale) but do not page on single events. onRecoverableError is the self-healed class: React encountered a problem, recovered automatically, and the user likely saw nothing — for hydration failures the original cause sits in error.cause. Before React 19, caught errors were also duplicate-logged to the console in development, which double-counted anything wired to console capture; React 19 reports each error once, through these hooks. Note what the root options still do not cover: handler throws and leaked rejections never enter React, so the two window listeners stay in the picture — the root callbacks replace guesswork for React-visible errors, not the global net.

Hydration errors: the recoverable class with a real cost

A hydration mismatch — server HTML disagreeing with the first client render — is the canonical onRecoverableError citizen. React discards the damaged server HTML and re-renders the affected tree on the client, so the user sees correct UI, maybe after a flicker. Treating these as fatal (the Hook’s screaming dashboard) is wrong twice: the user was not broken, and the alert noise buries real crashes. But ignoring them is wrong too — each mismatch means a subtree paid for server rendering and then rendered again on the client, and the usual causes (timestamps and locale formatting, Math.random, browser-only branches during render, an A/B test bucketing differently on each side) are deterministic bugs you can fix. The right posture: a separate, non-paging metric with a budget, investigated when the rate moves.

The pipeline: dedupe, symbolicate, tag — or drown

When you see a tracker flooded with duplicates and minified gibberish, you’re not looking at a capture problem — you’re looking at a pipeline problem. Raw capture is the easy half. The Hook’s flood came from the pipeline’s missing stages:

Dedupe. The same failure arrives through multiple doors: a boundary’s onError plus onCaughtError if you wired both; an error captured locally and then re-thrown; in development, StrictMode’s deliberate double-invoking of render functions (and double-running of effects) manufactures doubles of any render-path error — which is a feature for catching impure code, and a lie in your metrics if dev events reach the production tracker. Fingerprint events — message plus top stack frames plus release — count occurrences, and drop dev-mode noise at the source.

Symbolicate. Production stacks are minified: t.map is not a function at a.render (main.3f2c1.js:1:48212) locates nothing, and React’s own production error messages are compressed to numbered codes with a decoder URL. Without uploading source maps per build, every report is archaeology. The componentStack (from boundary or root callbacks) survives minification better — component names — but component names themselves can be mangled unless you preserve them or map them back.

Tag the release. A stack is only meaningful against the exact build that produced it. Tag every event with the release that shipped it, and the dashboard gains its two most useful queries: “did this start with the deploy?” and “is it gone after the rollback?” — the difference between debugging and guessing.