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.
TL;DR
- Next.js 15.5 ships its own copy of React (
next/dist/compiled/react-dom, version19.2.0-canary-0bdb9206-20250818). Upgradingreact-domin yourpackage.jsondoes not change what the App Router runs. - On long pages React Flight defers parts of the payload. If hydration starts before those parts arrive, a host element that suspends is replayed, and the replay forgets to rewind the hydration cursor. It claims its own first child as if it were itself, sees a mismatch, and throws #418.
- React fixed the replay upstream. We backport the same few lines into the bundled file at build time, from
next.config.ts, idempotently. - Trap: webpack's persistent cache keeps the unpatched chunk. Drop the browser bundle cache once after patching, or the fix silently does not ship.
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
suppressHydrationWarningonly silences text differences on one element. It does nothing for a structural mismatch, and here the structure was correct.- Making the component client-only (
dynamic(..., { ssr: false })) removes the error by removing server rendering, which is exactly what a help article needs for search engines. - Upgrading React in
package.jsondoes nothing: the App Router uses the copy compiled into Next.js. - Upgrading to Next.js 16 does fix it, but it is a major version with its own migration across many apps. We needed the fix the same day.
What actually happens
Three conditions have to line up:
- 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. - HTML in pieces. Behind a reverse proxy on a busy server, the document reaches the browser in several chunks. Hydration starts while
document.readyStateis stillloading, before the deferred rows have arrived. - 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:
- Idempotent. It looks for its own marker comment and for the upstream fix. If either is present, it leaves the file alone. When Next.js ships the fix, the script quietly becomes a no-op.
- Defensive. It only patches when every identifier it relies on is present in the file. A future React build with different internals is skipped, not corrupted.
- Runs everywhere the build runs. It is called at the top of
next.config.ts, so it executes fornext dev,next build, and on the server afternpm cireplacesnode_modules.
// 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
- The live React chunk now carries the corrected replay branch; the only #418 we saw after the first patch came from the stale webpack cache described above, and disappeared once the cache rule was fixed.
- The same script now sits in 19 Next.js app trees (portals, MVPs and products such as Curava, ELKASHIER Cloud and Spotra), so every new build of any of them gets the fix without anyone remembering to apply it.
- You can check any deployment in seconds: search the React chunk in
.next/static/chunksfor the minified form of the new condition (null!=n.stateNode&&(; the variable letter may differ).
Checklist if you see a random #418
- Does it happen only on long pages and only in production? Suspect streaming, not your markup.
- Check which React actually runs:
next/dist/compiled/react-dom/package.json, not your own dependency. - Reproduce with a proxy that splits the response into delayed chunks. If that triggers it, you are looking at a hydration-timing bug.
- Prefer the upstream fix (Next.js 16). If you cannot upgrade now, backport the exact upstream lines, guarded and idempotent.
- 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.