There are two kinds of bugs: the ones your code caused, and the ones your code gets blamed for. The second kind is worse, because you'll spend the first hour fixing code that was never broken.
That was my Tuesday morning. I'd just pushed a change to a React app I'm building, refreshed the page to eyeball it, and every single page was wearing a thin red line across the top — a browser overlay I'd never seen before. "Looks good," I thought, "except for the thing that's clearly wrong on every page." So I started hunting for what I'd broken.
The answer took about twenty minutes, and it was embarrassing in the best possible way: I hadn't broken anything. The red line was a hydration-mismatch overlay, and the thing that had "changed" my HTML wasn't my code at all. It was Chrome.
What hydration actually is
Server-side rendering sounds simple until you ask what happens after the HTML lands. The server renders your React tree to static HTML and sends it down so the page paints fast. Then the browser loads your JavaScript, and React "hydrates" — it walks the DOM, matches each element to its component, and wires up all the event handlers and state.
Here's the part that matters: hydration only works if the HTML the server sent is exactly what React expects to find. React diffs the two trees. If they don't match, it throws a mismatch error and, in development, paints a red overlay on the screen with the diff.
The error reads like an accusation. "Text content does not match server-rendered HTML." "Hydration failed because the initial UI does not match." Your first instinct — my first instinct — is to assume you rendered something that depends on the browser: a date, a random value, a window check. And nine times out of ten, that instinct is right.
This was the tenth time.
The attribute I didn't write
When I finally read the diff instead of skimming it, the offending line wasn't a value I'd rendered. It was an attribute I'd never seen in my life:
__gcrremoteframetoken
Sitting on my <html> tag, like it had always been there. Except the server never sent it. My code never wrote it. And yet there it was, on every page, on every refresh.
That string is Google Cast. Not an extension I installed — Cast is built into Chrome itself, on desktop and mobile. After the page loads but before React hydrates, Chrome quietly attaches its Cast token to the <html> element. It's benign. It's invisible. And it is exactly the kind of thing that breaks hydration, because the server doesn't know it exists.
So the sequence was: server sends clean HTML → Chrome mutates it → React arrives, compares, and finds an attribute it never rendered → React blames me.
My markup was fine. The server and client were rendering the identical tree. There was just a third party — the browser I was using to look at it — editing the document in between.
Why this one wasn't a "real" bug
It would be easy to wave a hand and say hydration errors are always your fault, go fix your code. And most of the time they are. But this specific class has a name in the React docs themselves: unavoidable mismatches caused by something outside your control.
The official escape hatch is a single prop, suppressHydrationWarning, dropped on the element that differs — in my case, on <html>. It tells React: I know this element's attributes might not match, and that's fine — don't warn, don't patch. React even documents it with a caveat I think about every time I use it: it only works one level deep, and it won't patch mismatched text. It's for attributes and timestamps, not for hiding real bugs.
And there's the discipline. The prop is a smoke detector you're allowed to mute once you've verified there's no fire. Here there was no fire: the only difference between server and client was a Cast token Chrome injects on its own. I added the prop with a comment explaining exactly why, because a future version of me is guaranteed to see suppressHydrationWarning and think "who left this in, and can I clean it up?" The answer has to be right there in the code.
What I'd tell past me
The whole thing taught me three things, in order of how much they stung.
First, read the diff before you blame the code. The error message and the little red overlay both point at the symptom. The actual culprit — an attribute named __gcrremoteframetoken — was sitting right there in plain text, and I'd glossed over it twice before it registered.
Second, your environment is part of your code's runtime. Browser extensions mutate the DOM. Grammarly adds data-gramm. Color pickers add cz-shortcut-listen. Chrome itself adds a Cast token. If a bug only reproduces in your browser and never in a clean profile or incognito, the difference might be the extensions you forgot were running.
Third, the escape hatch is for the cases you can prove are safe, and only those. suppressHydrationWarning is not a "make the red thing go away" button. Used carelessly, it buries real SSR bugs under a layer of silence. Used with a written reason, on an element you own, for a mismatch that is genuinely external — that's exactly what it's for.
The fix was one line, plus a comment. The actual markup never changed, because there was nothing wrong with it. Chrome had just added an attribute and let React take the blame.
The next time your app breaks in a way your code doesn't explain, what's the first thing you check before you touch anything?
