home

Diagnostics

LUM4006: Hydration mismatch

The DOM the server rendered does not match what the client renders while hydrating.

Severity: error · Category: islands and boundaries (4xxx)

Reported by: hydration (lumiose/dom/hydrate, run by the island loader), as a console warning in dev, in two cases: the server HTML does not match the client render (the island is then rendered on the client instead), or an async component's await has no recorded value (the client awaits it again). In production there is no warning; the same fallbacks apply.

#What it means

Hydration claims server-rendered nodes in order. If the client renders a different structure (other elements, a different branch, a different list length), or an async component's recorded await does not match its replay key, claiming fails.

#Example

tsx
export function Greeting() {
  return <p>{Math.random() > 0.5 ? <b>Hi</b> : <i>Hello</i>}</p>;
}

#How to fix it

Render the same output on both sides for the same props: move non-deterministic values (Math.random(), Date.now(), window sizes, locale-dependent formatting) into onMount or effects, or compute them on the server and pass them as props. Keep awaits in a stable order.