Bug: Incorrect Hydration Mismatch Detection during Suspense - "Hydration failed because the initial UI does not match what was rendered on the server."

[xiel]

React version: 18.0.0

Steps To Reproduce

1. Add a Suspense Boundary
2. Add a component that will suspend to load some data (faked).
3. Render at least one sibling component after the suspending component.
4. Render server-side using renderToPipeableStream()
5. Render client-side using hydrateRoot()

Reproductions in CodeSandbox:

• Reproduction 1 with Next.js Edit
• Reproduction 2 using renderToPipeableStream (based on example demo)

<>
  <h4>This headline hydrates fine. </h4>
  <SomethingA />{/* Will suspend on client and server */}
  <h3>💥 This element after the suspending Component triggers an error (only in development).</h3>
</>

The current behavior

• The sibling component following the suspending component is incorrectly seen as a hydration mismatch.
• Console will show errors (and Next.js will show big error overlay):

Warning: Expected server HTML to contain a matching <h3> in <div>.
    at h3
    at IndexPage
    at Suspense
    at App (webpack-internal:///./pages/_app.js:42:27)
    at ErrorBoundary (webpack-internal:///./node_modules/next/dist/compiled/@next/react-dev-overlay/client.js:8:20638)
    at ReactDevOverlay (webpack-internal:///./node_modules/next/dist/compiled/@next/react-dev-overlay/client.js:8:23179)
    at Container (webpack-internal:///./node_modules/next/dist/client/index.js:323:9)
    at AppContainer (webpack-internal:///./node_modules/next/dist/client/index.js:825:26)
    at Root (webpack-internal:///./node_modules/next/dist/client/index.js:949:27)

Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
    at throwOnHydrationMismatch (react-dom.development.js?ac89:14344:1)
    at tryToClaimNextHydratableInstance (react-dom.development.js?ac89:14372:1)
    at updateHostComponent$1 (react-dom.development.js?ac89:20636:1)
    at beginWork (react-dom.development.js?ac89:22373:1)
    at HTMLUnknownElement.callCallback (react-dom.development.js?ac89:4157:1)
    at Object.invokeGuardedCallbackDev (react-dom.development.js?ac89:4206:1)
    at invokeGuardedCallback (react-dom.development.js?ac89:4270:1)

• Depending on the location of the suspending component and their siblings, there are errors or no errors at all. When the suspending component is the last component, there are no errors logged.
• Error can be suppressed by wrapping the suspending component in a Suspense boundary directly

The expected behavior

• I expect to be able to use the same fetching mechanism using suspense on server and client in React v18.
  OR
• If this is unsupported usage, the errors should be more clear and consistent.

[gaearon]

Small repro: https://codesandbox.io/s/sleepy-dan-ghlh1u?file=/pages/_app.js

[gaearon]

Minimal repro without Next.js: https://codesandbox.io/s/compassionate-night-uzyxv1?file=/src/App.js

[gaearon]

Seems like a bug. Weird that I can't repro this in tests.

[gurkerl83]

Hi, I have seen this error lots of times in #23381. The issue was closed because Dom-Patching executed by React is not an alternative in React 18 anymore.

The problem with a sibling component following a suspending component seems quite related to what follows the suspending component can be seen as the mismatch itself. In my opinion, when a suspender alike component is involved, it is similar if you take direct action patching the DOM now on the client-side, on user code because react doesn`t do this not anymore.

The following findings ask if the suspected bug is related to the following interpretation.

...
Or patch up the HTML tree to prune the invisible branches before starting hydration.

It seems it is impossible to prune on the client side before starting hydration. The only way possible is involving an effect and a state. Even with a suspense boundary in place it is not possible.

Observation
Removing the throw statement in tryToClaimNextHydratableInstance works! An effect and state mutation is no longer required when handled inside a Suspense boundary.

The throw statement in popHydrationState ensures that an error is thrown if there are still actual differences between the server and client that have not been previously resolved through client intervention in a Suspense boundary.

I ask you to revisit the comments about the repetitive throw events in the samples.

The function tryToClaimNextHydratableInstance gets invoked inside the update functions of

• HostComponent - updateHostComponent on mount
• SuspenseComponent - updateSuspenseComponent on mount
• HostText - updateHostText on mount but not so interesting

The base question is if the throw statements in the function tryToClaimNextHydratableInstance are too early and unnecessary; the second sample extracted from popHydrationState throws them again and mentions an interesting comment.

Note:
Before the function tryToClaimNextHydratableInstance did not have any logic regarding the older DOM-Patching or the new approach followed to throw an error and catch them calling clear container.

Question???
Does an incomplete component (Suspense) don't need the time and opportunity to evolve and resolve the embodied promises (unknown what the shape of the return component is) before it gets canceled? If so this does not seem to be recognised because invoking tryToClaimNextHydratableInstance seems immediate in the update functions from above (on the mount).

function tryToClaimNextHydratableInstance(fiber: Fiber): void {
  if (!isHydrating) {
    return;
  }
  let nextInstance = nextHydratableInstance;
  if (!nextInstance) {
    if (shouldClientRenderOnMismatch(fiber)) {
      warnNonhydratedInstance((hydrationParentFiber: any), fiber);
      throwOnHydrationMismatch(fiber);            <== !!!!!!!!! This is too strict; client-side 
                                                  render decisions are not respected
                                                  before hydration starts. A typical 
                                                  use case is to avoid the initial render 
                                                  when the client has more info such as
                                                  screen size; currently passing an effect 
                                                  executing a state mutation is required; 
                                                  client-side render decisions need an 
                                                  additional render on the client. 

                                                  Unfortunately this is required even when
                                                  render-decisions and components are
                                                  embedded inside a Suspense boundary. :'( 
                                                  !!!!!!!!!
    }
    // Nothing to hydrate. Make it an insertion.
    insertNonHydratedInstance((hydrationParentFiber: any), fiber);
    isHydrating = false;
    hydrationParentFiber = fiber;
    return;
  }
  const firstAttemptedInstance = nextInstance;
  if (!tryHydrate(fiber, nextInstance)) {
    if (shouldClientRenderOnMismatch(fiber)) {
      warnNonhydratedInstance((hydrationParentFiber: any), fiber);
      throwOnHydrationMismatch(fiber);       <== !!!!!!!!! Also too strict; 
                                             same as previous comment 
                                             !!!!!!!!!
    }
    // If we can't hydrate this instance let's try the next one.
    // We use this as a heuristic. It's based on intuition and not data so it
    // might be flawed or unnecessary.
    nextInstance = getNextHydratableSibling(firstAttemptedInstance);
    const prevHydrationParentFiber: Fiber = (hydrationParentFiber: any);
    if (!nextInstance || !tryHydrate(fiber, nextInstance)) {
      // Nothing to hydrate. Make it an insertion.
      insertNonHydratedInstance((hydrationParentFiber: any), fiber);
      isHydrating = false;
      hydrationParentFiber = fiber;
      return;
    }
    // We matched the next one, we'll now assume that the first one was
    // superfluous and we'll delete it. Since we can't eagerly delete it
    // we'll have to schedule a deletion. To do that, this node needs a dummy
    // fiber associated with it.
    deleteHydratableInstance(prevHydrationParentFiber, firstAttemptedInstance);
  }
}

The function popHydrationState gets called after tryToClaimNextHydratableInstance in the respective update functions from above.

I copied the relevant section of the popHydrationState function. The comment in the code makes me wonder if this is the only position where the throw of a hydration mismatch makes sense. As mentioned above, the popHydrationState gets executed after the update functions for Host, Suspense, and Text.

function popHydrationState(fiber: Fiber): boolean {
  ...
  // If we have any remaining hydratable nodes, we need to delete them now.
  // We only do this deeper than head and body since they tend to have random
  // other nodes in them. We also ignore components with pure text content in
  // side of them. We also don't delete anything inside the root container.
  if (
    fiber.tag !== HostRoot &&
    (fiber.tag !== HostComponent ||
      (shouldDeleteUnhydratedTailInstances(fiber.type) &&
        !shouldSetTextContent(fiber.type, fiber.memoizedProps)))
  ) {
    let nextInstance = nextHydratableInstance;
    if (nextInstance) {
      if (shouldClientRenderOnMismatch(fiber)) {
        warnIfUnhydratedTailNodes(fiber);
        throwOnHydrationMismatch(fiber);        <== !!!!!!!!! Reasonable, not to patch the DOM, 
                                                but this is handled by the application directly;
                                                see comments from the previous sample 
                                                !!!!!!!!!
      } else {
        while (nextInstance) {
          deleteHydratableInstance(fiber, nextInstance);
          nextInstance = getNextHydratableSibling(nextInstance);
        }
      }
    }
  }
...
}

Thx!

[xiel]

Please see my comment in the PR: #24404 (comment)