Use a React Error Boundary when a rendering failure should replace part of the interface with fallback UI. Use browser global handlers to report certain uncaught failures—synchronous script errors and unhandled Promise rejections—but not as a substitute for that UI recovery. Neither mechanism catches every kind of error.
What each mechanism is for
An Error Boundary is a React component that handles errors thrown by descendant components while React renders them. It can display a fallback for the affected part of the tree, while componentDidCatch can report the error and component stack. See React’s Component reference.
As an Amazon Associate I earn from qualifying purchases.
Browser global handling operates at a different level. The window error event reports synchronous script errors that reach the global scope; unhandledrejection reports a Promise rejection that has no rejection handler. These events are useful for diagnostics, but they do not turn a failed React subtree into fallback UI. MDN documents the distinct events for script and resource errors and unhandled Promise rejections.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Which errors go where?
| Failure | Error Boundary | Browser global handler |
|---|---|---|
| Descendant throws during React rendering | Yes. It can show fallback UI and report details. | React says caught errors bubble to window in development, but not in production. Do not rely on this for production reporting. |
| Exception thrown in an event handler | No. Handle it in the event handler or the action flow. | An uncaught synchronous exception may reach the window error event. This reports the failure; it does not recover the React UI. |
Exception in a setTimeout or requestAnimationFrame callback |
Generally no; it occurs outside the descendant render being guarded. | An uncaught synchronous exception may reach the window error event. |
| Promise rejection without a handler | Generally no, unless it is surfaced through a React-supported path. | unhandledrejection is the relevant event. Some cross-origin rejections do not fire it. |
Rejected Promise read with React use(promise) |
Yes. React sends the rejection to the nearest Error Boundary. | Do not treat the global rejection event as the recovery mechanism for this React-handled path. |
| Error in the boundary itself | No. A boundary does not catch errors thrown by itself. | A synchronous error may reach a global handler if it escapes to the global scope. |
| Failed image, script, or other resource load | Not an ordinary descendant-rendering error. | The error event may be dispatched on the failed element rather than bubbling to window, so a window listener is not a universal resource-failure detector. |
| Server-side rendering failure | Outside the ordinary Error Boundary guarantee. | Browser window handlers do not handle server execution; use the server runtime’s error handling separately. |
What Error Boundaries exclude—and the React exceptions
React’s documented exclusions include event handlers, server-side rendering, errors thrown by the boundary itself, and most asynchronous callbacks. The practical test is whether the error occurs while React renders a descendant, not merely whether the code belongs to a React application.
#1 Best Overall
There are two relevant React paths involving asynchronous work. An error or rejection inside the function passed to useTransition’s startTransition can reach an Error Boundary, as described in the useTransition reference. A rejected Promise read with use(promise) also reaches the nearest boundary; see the use reference. The latter documentation also notes that the Promise should be cached so it is stable across renders.
Implement a boundary around the UI that should recover
React’s documented boundary pattern uses a class component. Put the boundary around a meaningful recovery area—such as a conversation list or an individual message—so a failure replaces only the UI that cannot continue.
- Implement
static getDerivedStateFromError(error)to set state that selects the fallback UI. - Render the normal descendants when there is no error, and render a useful fallback when that state is set.
- Implement
componentDidCatch(error, info)when you need to report the failure. React providesinfo.componentStackfor component-level context.
React’s reference does not provide a direct function-component equivalent for componentDidCatch; it points to the react-error-boundary package as an alternative. Whichever pattern you choose, keep recovery at the boundary and send diagnostics through a deliberate reporting path.
Configure global listeners for uncaught diagnostics
Use addEventListener when listening for browser-level failures. The two events represent different failure types:
window.addEventListener("error", callback)receives an event object for global script errors. MDN distinguishes this from the historicalwindow.onerrorproperty, which receives five arguments.window.addEventListener("unhandledrejection", callback)observes a Promise rejection that remains without a handler. Cross-origin restrictions mean some rejections are not exposed through this event.
Be cautious about suppressing default reports. Returning true from the historical window.onerror property suppresses the browser’s default console report, but it does not resume the failed script. Calling preventDefault() on an unhandledrejection event likewise cancels default reporting; do so only when your application deliberately takes over that responsibility.
React 19 adds root-level reporting callbacks
React 19 adds onCaughtError for errors caught by an Error Boundary and onUncaughtError for errors not caught by a boundary, alongside the existing onRecoverableError callback. They are configured as root options, so setup depends on how the React root is created. See the React 19 release notes.
These callbacks provide a React-aware route for reporting; they do not replace the boundary’s fallback UI. A useful division is to let the boundary handle local recovery, and use boundary logging, React 19 root callbacks, or browser global events to report the failures each path actually observes. Avoid assuming that a single global listener receives every boundary-caught error: React documents that such errors bubble to window in development but not in production.
Quick Recap
Best Value
Choose the handler by the failure’s path
- Render failure in a component subtree: add or refine an Error Boundary where the UI can recover; report through
componentDidCatchor, on React 19, the root’sonCaughtError. - Uncaught synchronous exception outside rendering: handle it at the operation that can respond appropriately, and use the global
errorevent as an additional diagnostic path. - Promise rejection: attach a rejection handler when the operation is initiated. If React reads the rejected Promise with
use, let the nearest boundary provide UI recovery; for a rejection left unhandled,unhandledrejectionis the browser-level diagnostic event. - Server-side failure: handle and report it in the server runtime. A browser window listener cannot observe server execution.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
