React Reference ยท react-dom Client APIs
createRoot and hydrateRoot options
Reference for the options object of createRoot and hydrateRoot: onUncaughtError, onCaughtError, onRecoverableError and identifierPrefix, with examples.
The optional second argument of createRoot (third argument of hydrateRoot) is an options object. Its main job in React 19 is to let you decide what happens to errors: where they are logged, what is reported to a monitoring service, and whether the default console output is replaced.
Three callbacks cover the three kinds of error React can see, plus one option for generating unique IDs. All are optional; without them React logs to the console and reports uncaught errors with window.reportError.
const root = createRoot(container, { identifierPrefix: 'app-', onUncaughtError(error, info) {}, onCaughtError(error, info) {}, onRecoverableError(error, info) {}, });
Try it
Syntax
createRoot(domNode, { identifierPrefix?: string, onUncaughtError?: (error: unknown, info: { componentStack?: string }) => void, onCaughtError?: (error: unknown, info: { componentStack?: string, errorBoundary?: Component }) => void, onRecoverableError?: (error: unknown, info: { componentStack?: string }) => void, })
| Option | When it runs |
|---|---|
onUncaughtError |
An error was thrown during rendering, and no error boundary caught it. The tree is unmounted. Default: window.reportError. |
onCaughtError |
An error boundary caught the error. info.errorBoundary is the boundary instance. Default: console.error. |
onRecoverableError |
React recovered by itself, typically by falling back to client rendering after a hydration mismatch. The cause property of the error often holds the details. Default: reportError. |
identifierPrefix |
A string prepended to every useId value from this root. |
hydrateRoot accepts the same four options.
Usage notes
- Replacing a callback replaces the default logging. If you only want to add reporting, also call
console.error(error)yourself. - Use
onUncaughtErrorandonCaughtErrorfor a single place that sends crashes to a monitoring service, instead of wiring the same code into every boundary. info.componentStackis a string showing which components were rendering. In production builds it is minified unless source maps are applied.- Errors thrown in event handlers or async code are not reported by these callbacks; they go to the browser (
window.onerror) as usual. onRecoverableErroris the practical tool for finding hydration errors: mismatches are recoverable, so without a handler they appear only as console messages.identifierPrefixmatters when several React roots share one page, or when server-rendered HTML must match client IDs. Use the same prefix on the server and inhydrateRoot.- These callbacks arrived in React 19. React 18 only had
onRecoverableError; the oldonCaughtError-like behavior wascomponentDidCatchinside boundaries. - Do not throw from a callback. That would hide the original problem.