`<Hydrate when={visible()}>` throws React #467 when the gate resolves during a replayed mount #8652
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
<Hydrate when={visible()}> sometimes throws React #467 ("Update hook called on initial render") from HydrationBoundary in hydration/visible.tsx. During hydration it is followed by #422 and the boundary is client-rendered, so the server HTML and the deferred hydration are lost for that section.
HydrationBoundary suspends on the gate before it calls its only hook:
if (!g.r) {
if (!reactUse) throw g.p
reactUse(g.p)
}
React.useEffect(() => { o?.() }, [o])
If the gate resolves after use(g.p) suspends but before React abandons that render, React replays the suspended mount. The replay passes the gate and reaches useEffect, but the first attempt recorded no hooks and the fiber has no alternate, so React throws #467. It depends on timing, which is why it is intermittent in an app.
GenericHydrate avoids this: HydrationGate has no hooks and the effects live in HydratedBoundary.
Complete minimal reproducer#
Unit test (jsdom, React 19), deterministic: https://github.com/ethan-huo/router/blob/fix/visible-hydration-hook-order/packages/react-start-client/src/tests/visible.test.tsx
A component rendered before the boundary reveals it from a microtask during a transition re-render, while the boundary is still showing its fallback. onRecoverableError receives "Update hook called on initial render" at visible.tsx, and React recovers with a synchronous render of the whole root.
Steps to Reproduce the Bug#
pnpm nx run @tanstack/react-start-client:test:unit -- src/tests/visible.test.tsxonmainwith the test above added.- The test fails with the #467 error collected from
onRecoverableError.
In a production app with four visible() sections below the fold, Chrome logs #467 then #422 on 2–3 of 15 page loads.
Expected behavior#
A visible() boundary never throws while it hydrates or mounts, and keeps its server HTML until it hydrates.
Platform#
@tanstack/react-start-client1.168.37 (unchanged onmainat f6d21de)react/react-dom19.3.0- Chrome 155, macOS
Additional context#
Fix: call the effect before the gate. With that change the app logs no #467/#422 in 25 of 25 loads. PR to follow.
Sheraff(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.