Support specifying onRecoverableError for ReactDOM.hydrateRoot

[vpontis]

Describe the feature you'd like to request

With the upgrade to React 18, we are getting a lot of hydration errors. These can be hard to debug on production because the source maps are minified.

I'd like to see the ability to pass in onRecoverableError to hydrateRoot which will allow better logging of errors to help us track down hydration issues. (This would also let us ignore hydration errors if we decide to, or not send them to Sentry.)

Describe the solution you'd like

You can define an onRecoverableError in next.config.js which will be called on hydrateRoot .

Describe alternatives you've considered

I've tried tracking down hydration errors and I've found some of them, but not all of them.

[gurkerl83]

React handles recoverable errors in onRecoverableError. Either a custom function is passed to hydrateRoot; otherwise React's default implementation is used, which uses the browser's reportError function. Errors that are recoverable in isolation are always reported to the user in a modal-style error dialogue, and are not handled quietly.

NextJs uses only two arguments (Dom element, React element) when calling hydrateRoot. The third possible argument to specify hydrate options along with the onRecoverableError field, in which the error response of recoverable errors can be adjusted, is not used at all.

In principle, the problem can be addressed on the NextJs or React side, but an adjustment is necessary on the respective side.

Option 1: NextJs - Extension of the NextJs configuration
NextJs, as shown in the issue, does not allow an option in its configuration to specify hydrate options (specifically onRecoverableError) that are passed from NextJs to hydrateRoot.

Con: Valid only for NextJs, other libraries that hide the call to hydrateRoot from the user and do not allow hydrate options are still affected by the issue.

Option 2: Adaptation of React's default implementation to onRecoverableError

Errors related to suspense are called recoverable. These are resolved through React internal workflows by reverting to a client-based rendering within a Suspense Boundary. As these errors are handled, jumping back to a client-based rendering does not constitute a critical error. A hint in the console about the cause that led to the switch to a client-based rendering should be sufficient.

Extract from ReactDOMRoot

const defaultOnRecoverableError =
   typeof reportError === 'function'
      ?  // In modern browsers, reportError will dispatch an error event, emulating an uncaught JavaScript error.
      reportError
      : (error: mixed) => {
         // In older browsers and test environments, fallback to console.error.
         // eslint-disable-next-line react-internal/no-production-logging, react-internal/warning-args.
      console.error(error);
      };

• Removal of browser-based API reportError to handle recoverable errors.

https://developer.mozilla.org/en-US/docs/Web/API/reportError

As pointed out in the comment, an uncaught error is thrown even if it was classified as recoverable within React. React internal processes have responded to such errors, for example by server-side and client-side content not matching.

The error caused by reportError must in turn be caught by a global error handler. This seems to be a bit excessive.

window.onerror = function(message, source, lineno, colno, error) {
  console.log('message:' + error.message + ', lineno: ' + lineno );
  return true;
};

• Output the error only in the console, as is the case in older browsers and test environments.

In React based libraries that do not allow or support configuration of hydrate options, the problem must be described as recurring. Especially in background that React notices recoverable errors and actively counteracts them, conversely should resort to a less aggressive behaviour to bring this to the developer's attention.

ReportError is a very young API - Supported from October 2021 in Edge, Firefox and Chrome, not before.

https://caniuse.com/?search=reportError

LogRecoverableError was originally introduced in ReactDOMHostConfig.
facebook/react@848e802

The following refactoring has changed the name and position.
facebook/react@efd8f64

logRecoverableError => defaultOnRecoverableError
ReactDOMHostConfig => ReactDomRoot

I will open an issue in NextJs and React respectively.

facebook/react#24563

Thx!

[BrooceLR]

This should really be converted back to an issue. Theres plenty of users confused by minified errors which can sometimes only be reproduced in production. Supporting onRecoverableError would make isolating, reporting and reproducing these issues so much easier.

[hamlim]

Hate to be the person to drop by and add a plus one to a discussion but we'd find this feature really valuable to help us debug these errors!

We'd be happy to also contribute this feature if given some guidance on the best place to support this (my limited understanding is that next.config.js isn't loaded on the client, so we wouldn't be able to leverage that to define a function for this handler, I guess it could be defined in something like _app, or layout.tsx in the new infra [but that gets tricky if it's a server component 🤔 ])

[AbhiPrasad]

Would be great to see this get exposed. We've been chatting about it here facebook/react#26224, and it seems Astro, Remix, Gatsby all already expose this functionality so Next.js just has to catch up!

if you want a super hacky approach, you can try and monkey patch hydrateRoot with proxies to accomplish this. getsentry/sentry-javascript#7293. Warning though that this could break if next/react changes their API in any way.

// Run this code before react components get mounted.
// If you use Sentry you can put this in your sentry.client.config.js
import * as client from "react-dom/client";

const oldClientHydrateRoot = client.hydrateRoot;
client.hydrateRoot = new Proxy(oldClientHydrateRoot, {
  apply: (wrappingTarget, thisArg, args) => {
    const oldOnRecoverableError = args[2].onRecoverableError;

    args[2].onRecoverableError = new Proxy(oldOnRecoverableError, {
      apply: (inner_wrappingTarget, inner_thisArg, inner_args) => {
        const error = inner_args[0];
        const errorInfo = inner_args[1];
 
        // log out error + `componentStack` in production
        console.log(error, errorInfo.componentStack)

        // if y'all use Sentry (https://sentry.io/for/nextjs/)
        // Sentry.captureException(error, { contexts: { react: { componentStack } } });
    });

    return wrappingTarget.apply(thisArg, args);
  },
});

^ We use the above to get the component stack logged in production!

[JohnRPB]

I tried this and it didn't work for me, probably because I wasn't able to successfully monkey-patch the dom client before React mounted. But I found success instead monkey-patching the reportError() function in the client wrapper for my root layout:

const isBrowser = typeof window !== "undefined";

if (isBrowser) {
  // Obtain the `reportError` function from the global scope
  const reportError = window.reportError;
  // Monkey-patch the function to ignore specific errors
  window.reportError = (...args) => {
    const [ error ] = args;
    // Ignore error if it contains the text "strict-client-only"
    if (!error.message.includes("strict-client-only")) reportError(...args);
  }
}

This not only hides the console errors, it also prevents the popups, a little surprisingly. A different option for folks struggling with the first solution.

The error message BTW is unique to me, because I was throwing errors manually; you can adapt it to your use-case.

[AndersDJohnson]

Relates to #47542.

[AndersDJohnson]

Principal Engineer on the Web team at @target here - we would find this extremely useful as well!

[AndersDJohnson]

Proposing #50943 as a potential partial solution here, at least for @AbhiPrasad's use case above, which my teams also have.

[iamkd]

I think it makes sense to have it exposed completely as well. There is a pattern described in React docs that enables real client-only components without use of dynamic or lazy. The problem is that throwing an error will pollute the logs even though it is expected to be recoverable.

Other frameworks like Remix do not hide the hydrateRoot call. This allows us to patch the onRecoverableError handler and ignore the expected recoverable errors or add better logging etc. Also confirmed by a member of React team in this issue: reactjs/react.dev#6106 (comment)

[JohnRPB]

Actually, since I'm using the experimental React release inside NextJS, the postpone API proved to be a much better approach and less of an anti-pattern:

import { unstable_postpone } from 'react';

function ClientOnlyComponent(props) {
    if (isServer) unstable_postpone("client only");
    ...

Thank you to the person who suggested this above, it worked wonders!

[JohnRPB]

Unfortunately I need to report that the above solution did not work, and only appeared to work because ironically it also threw an error.

In NextJS 14.0.4 (latest), unstable_postpone does not appear in the webpack-bundled import of React. This isn't documented anywhere, but I can see in the source code that NextJS is not exposing some experimental features out of what is, after all, still an unstable version of React, even though they are actually using them internally.

Rather than spend more time on this, I wanted to share the work-around I came up with, which involves monkey-patching the browser's reportError function:

const isBrowser = typeof window !== "undefined";

if (isBrowser) {
  // Obtain the `reportError` function from the global scope
  const reportError = window.reportError;
  // Monkey-patch the function to ignore specific errors
  window.reportError = (...args) => {
    const [ error ] = args;
    // Ignore error if it contains the text "strict-client-only"
    if (!error.message.includes("strict-client-only")) reportError(...args);
  }
}

This actually works better than I thought; it doesn't just hide the console errors, it prevents the popups too. I put it in the client-wrapper for my root layout.

[AndrewIngram]

Unfortunately I need to report that the above solution did not work, and only appeared to work because ironically it also threw an error.

In NextJS 14.0.4 (latest), unstable_postpone does not appear in the webpack-bundled import of React. This isn't documented anywhere, but I can see in the source code that NextJS is not exposing some experimental features out of what is, after all, still an unstable version of React, even though they are actually using them internally.

Rather than spend more time on this, I wanted to share the work-around I came up with, which involves monkey-patching the browser's reportError function:

const isBrowser = typeof window !== "undefined";



if (isBrowser) {

  // Obtain the `reportError` function from the global scope

  const reportError = window.reportError;

  // Monkey-patch the function to ignore specific errors

  window.reportError = (...args) => {

    const [ error ] = args;

    // Ignore error if it contains the text "strict-client-only"

    if (!error.message.includes("strict-client-only")) reportError(...args);

  }

}

This actually works better than I thought; it doesn't just hide the console errors, it prevents the popups too. I put it in the client-wrapper for my root layout.

If you enable the ppr experiment, you also get access to the postpone API (because ppr uses it internally) - https://nextjs.org/docs/app/api-reference/next-config-js/partial-prerendering

[JohnRPB]

Thanks @AndrewIngram, I'll check this out! Might stick with the reportError() work-around for now given the bleeding-edge status of ppr, but maybe by the time I'm ready to push to production...

[JohnRPB]

Just wanted to throw in a note here that the Postpone API is tied to dynamic rendering, so keep that in mind; your pages will render dynamically with PPR if you enable it.

[samijaber]

Far from being an optimal solution, but I built a modal that shows a diff of client vs server rendered DOM when hydration errors occur: https://github.com/BuilderIO/hydration-overlay/

Somewhat of a workaround until this discussion bears fruit, or Hydration error handling improves within React itself.

[AbhiPrasad]

For production hydration errors you can use Sentry Session Replay to get a hydration error diff (both HTML and visual diff)!

https://changelog.getsentry.com/announcements/diff-hydration-errors-with-replay

[MikelArnaiz]

@AbhiPrasad I tried your hack and although I log some info I still unable to retrieve what caused the hydration error.

In Next 14 a diff was introduced that shows a diff with exactly what the server and the client rendered. It is also log to the console:

But the info available onRecoverableError doesn't include the diff

How do I get this diff? What else are you at doing to be able to display a diff in Sentry replay?

[AbhiPrasad]

How do I get this diff? What else are you at doing to be able to display a diff in Sentry replay?

Unfortunately react doesn't expose this exact diff, and the error is a lot less useful in production environments as well.

I think Next.js does some extra logic to calculate this, but it's not publicly accessible API.

With sentry session replay it snapshots the HTML before and after the hydration error is thrown, which is how it can show the exact diff.