GeoTech

Engineering / Case study

Random React hydration error #418 on long pages in Next.js 15.5, and the build-time fix

GeoTech Engineering · · 8 min read

Next.jsReactHydrationDebugging

Some of our help articles threw React error #418, "the server rendered HTML didn't match the client", on a small share of real page loads. Never in development, never on a fast connection, never twice in a row for the same person. The page then threw away its server HTML and redrew itself in the browser, which users saw as a flash and a slower page. The cause was not in our code. It was a bug in the React build that Next.js 15.5 bundles, and it only fires when the HTML arrives in pieces. This is how we found it and how we fixed it without waiting for Next.js 16.

1–8%of live loads hit #418 on long pages
0reproductions on a local machine
19Next.js app trees now carry the patch

TL;DR

The problem: an error you cannot reproduce

The reports came from our error collection, not from users. #418 appeared on long pages only: help articles with related links, a contact card and a footer below a long body. Short pages were clean. Loading the same URL a hundred times on a laptop produced nothing.

The usual suspects for #418 are well known: a date rendered in two time zones, Math.random() in render, a browser extension injecting attributes, invalid nesting such as a <div> inside a <p>. We went through all of them. None explained an error that depends on page length and on the network, and none explained why the same HTML hydrated cleanly most of the time.

Why the usual fixes do not help

What actually happens

Three conditions have to line up:

  1. Deferred rows. When a part of the React Flight payload is larger than 3200 bytes, the server defers it into a separate row ($L17, $L1f…) that is streamed later in its own inline <script>. On a long article, the related links, the contact card and the footer landed in such rows.
  2. HTML in pieces. Behind a reverse proxy on a busy server, the document reaches the browser in several chunks. Hydration starts while document.readyState is still loading, before the deferred rows have arrived.
  3. A replay. The page shell, a plain <div class="min-h-dvh">, claims its DOM node during hydration and then suspends on a deferred row that is not there yet. When the row arrives React replays that element. In this React build the replay of a host element does not move the hydration cursor back to the element's own node. It claims the next node instead: its own first child, a <header>. React expects a <div>, finds a <header>, and reports #418.

That explains every symptom. Short pages have no deferred rows. Local development delivers the HTML in one piece, so hydration never starts early. A fast connection usually delivers the rows before the shell suspends. The error rate depends on server load, which is why it moved around between days.

We confirmed it by putting a small proxy in front of a local build that split the response into chunks with delays between them. With the proxy, #418 reproduced on demand. Without it, never.

The fix: backport React's own correction at build time

React later corrected the replay: before replaying a host component during hydration, it pops back to the right parent and sets the next hydratable node to the element's own DOM node. That code exists in the React that Next.js 16 bundles. We insert exactly that branch into the bundled file, in the case 5 (host component) arm of the replay function:

case 5:
  resetHooksOnUnwind(unitOfWork);
  /* gt: rewind hydration on host replay */
  unitOfWork === hydrationParentFiber &&
    (isHydrating
      ? (popToNextHostParent(unitOfWork),
         5 === unitOfWork.tag && null != unitOfWork.stateNode &&
         (nextHydratableInstance = unitOfWork.stateNode))
      : (popToNextHostParent(unitOfWork), (isHydrating = !0)));
default:

The script that applies it is about 60 lines and follows three rules:

// next.config.ts
import { patchReactReplay } from "./scripts/patch-react-replay.cjs";
patchReactReplay();   // backport of React's hydration-replay fix (Next 15.5)

The mistake: the fix that did not ship

After the first rollout, a server build produced the same React chunk hash as before. The file in node_modules was patched; the chunk in .next/static was not. Webpack's persistent cache keys dependencies by package version, and the version string had not changed, so it reused the chunk it had built from the unpatched file.

We added a cache drop: whenever the script patches, it deletes the client-* folders under .next/cache/webpack. That was not enough either. On one machine another process had patched node_modules first, so our script found nothing to patch and dropped nothing, while the cache still held the old chunk. A local test with the chunking proxy still showed #418 on 3 of 180 loads.

The final version writes a marker file into the webpack cache folder after dropping it, and drops the browser bundle cache once more for any cache that does not carry the marker. Server caches are left alone, so build times barely change.

Result

Checklist if you see a random #418

  1. Does it happen only on long pages and only in production? Suspect streaming, not your markup.
  2. Check which React actually runs: next/dist/compiled/react-dom/package.json, not your own dependency.
  3. Reproduce with a proxy that splits the response into delayed chunks. If that triggers it, you are looking at a hydration-timing bug.
  4. Prefer the upstream fix (Next.js 16). If you cannot upgrade now, backport the exact upstream lines, guarded and idempotent.
  5. After patching anything in node_modules, clear the browser bundle cache and verify the shipped chunk, not the source file.

Need this?

GeoTech builds and runs production Next.js and Node applications for clinics, retailers and service businesses, and we chase the bugs that only appear for real users. If your app shows errors you cannot reproduce, or you want a second pair of eyes on performance and reliability, talk to us.