The first client pass over server-rendered markup finds nodes that do not match its description. Which code causes that, and how do you fix it?

## Why the first pass has to match When a renderer adopts nodes it did not create, it walks the description and the existing nodes together, position by position, assuming each node it finds is the one the description intends. It has no way to *search*: the whole saving of the mode comes from not re-writing what is already there. So the invariant is strict — **the first described output in the browser must be the same tree the upstream render produced**, node for node. After that first pass the runtime owns the tree again and ordinary update rules apply, which is why the constraint is so often misremembered as a general rule about output. ## The four classes that break it 1. **A value only one side can read.** Viewport size, a stored preference, a device or capability check, a value that exists in the browser but not where the markup was produced. The producer renders one branch, the browser computes another. 2. **A clock or a random source.** A timestamp, a relative time string, a duration, a shuffled order, a generated identifier. The two renders happen at different moments and, for random values, from different draws. 3. **Locale-, timezone- or currency-dependent formatting.** The markup is produced in the producer's locale and timezone; the browser formats in the user's. A date, a number separator, a currency symbol or a sort order differs even though the input data is identical. 4. **Markup the parser corrected.** The description nests elements in a way the host's parser does not allow, so it closes, moves or drops nodes while building the tree. The document then legitimately does not contain the described structure, and the walk cannot line up. This one is the most confusing to debug, because nothing in the code looks volatile. A fifth cause deserves a mention: **different data**. If the producer and the browser resolve the same query against different state — a cache, a mutation in between, a per-request value not passed along — the output differs for reasons that have nothing to do with rendering. ## What the runtime does about it Two responses, chosen by case: - **Patch in place.** Text or an attribute differs but the structure lines up: keep the node, write the client's value, carry on, and usually report the difference. - **Discard and rebuild.** The structure differs, so lockstep is impossible: drop that subtree and re-run it in create mode. The second is what makes mismatches expensive. The upstream work for that region is thrown away *after* it was painted, so the user sees content replaced, often with a layout shift, and the closer the mismatch is to the root the larger the rebuilt region. A mismatch is therefore both a correctness signal and a performance defect. ## The remedies | Fix | What it does | What it costs | Use it for | |---|---|---|---| | Render the volatile part after attach | both sides output the same neutral version; the real value appears in a post-attach callback | one extra frame, and layout shift if the two sizes differ | environment reads, clocks, locale formatting where a neutral placeholder is acceptable | | Mark the subtree as deliberately unmatched | the runtime accepts a difference there, keeps the client value, and does not report it | the region is not really shared work any more; too broad a mark hides real defects | a small, genuinely client-specific value such as a rendered local time | | Pass the producer's value through | the browser's first pass uses the same input the producer used, then updates later if needed | the value has to be serialised with the page | data differences, and identifiers that must be stable | | Fix the structure | the description becomes valid, so the parser stops correcting it | none — it was a bug | corrected markup, always | The second row is the one most often abused. Marking a subtree as unmatched is a narrow tool: it makes a *value* difference acceptable, and it does not rescue a structural difference — the walk still fails. Reaching for it whenever a warning appears converts a loud, cheap-to-fix problem into a silent one. ## How to work one out in practice 1. Read the reported node and ask which of the four classes could make *that* node differ. 2. Check the description for invalid nesting before suspecting anything dynamic; a structural report with no dynamic values is almost always the parser. 3. For a value difference, find the input: is it read from the environment, from a clock, from a formatter with an implicit locale or zone, or from data that the two sides resolved separately? 4. Choose the fix by whether the value is *meant* to be shared. If it is, make both sides compute it from the same input. If it genuinely cannot be, move it after the attach pass or mark it. ## Where frameworks differ Runtimes vary in how loudly they report, how much they patch before giving up, and whether a failure is scoped to a subtree boundary or escalates toward the root. Some emit position markers so the walk can resynchronise. What none of them can do is guess which of the two trees was right — that is why the first pass is the client's contract to keep.