Rejected Promises Bypass React Error Boundaries: Where Should Async Failures Land?

Documented gap: boundaries skip handlers and async code

React Error Boundaries catch errors thrown during rendering, in lifecycle methods, and in constructors below them, but the documentation is explicit that they do not catch errors in event handlers or asynchronous callbacks such as promise rejections, setTimeout, or requestAnimationFrame. In a React 18 single-page app, a rejected fetch inside an onClick handler or an effect escapes every boundary in the tree.

The surrounding constraints are documented too: a render-time error with no boundary above it unmounts the whole tree (deliberate behavior since React 16), server-side rendering does not support boundaries, and componentDidCatch's info.componentStack is diagnostic text whose formatting is not a stable API.

The open decision is that React provides no built-in way to route arbitrary async rejections into a boundary. Teams can wrap handler bodies in try/catch and set error state to trigger a fallback render, rely on router-level error elements, or adopt a third-party wrapper — and the sensible choice appears to vary with whether data is fetched during render or in effects.

For a React 18 codebase, which strategy should be the default?

• Should async failures be normalized into render-time state so existing boundaries show the fallback, or handled at each call site?
• Should fallback UI live per component, per route, or in one app-level boundary?
• Which approach still works under SSR, where boundaries never run?