Skip to content
Tutorials Center
My learning

Topics

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.

JSX
const root = createRoot(container, {
  identifierPrefix: 'app-',
  onUncaughtError(error, info) {},
  onCaughtError(error, info) {},
  onRecoverableError(error, info) {},
});

Try it

Caught and uncaught errors
identifierPrefix with useId

Syntax

JSX
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 onUncaughtError and onCaughtError for a single place that sends crashes to a monitoring service, instead of wiring the same code into every boundary.
  • info.componentStack is 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.
  • onRecoverableError is the practical tool for finding hydration errors: mismatches are recoverable, so without a handler they appear only as console messages.
  • identifierPrefix matters when several React roots share one page, or when server-rendered HTML must match client IDs. Use the same prefix on the server and in hydrateRoot.
  • These callbacks arrived in React 19. React 18 only had onRecoverableError; the old onCaughtError-like behavior was componentDidCatch inside boundaries.
  • Do not throw from a callback. That would hide the original problem.