Websites · Glossary
What is a hydration error in React?
A hydration error happens when React attaches to HTML that was rendered on the server or at build time and finds that its own first render in the browser produces different markup. React then warns, may throw away the server HTML and render again on the client, which costs speed and can make content flicker or break.
Hydration is the step where a server rendered page becomes interactive. A hydration error means the two renders did not match, almost always because the code read something in the browser that the server could not know.
Nuwan Madhusanka · Co-founder
4 min read · Published
| Cause | Why the renders differ | Fix |
|---|---|---|
| Dates and times | The server and the browser are in different time zones or render seconds apart | Render a fixed value first and update it in an effect, or format with a set time zone |
| Random values | Math.random() or new ids differ between renders | Use React's useId or generate values once on the server |
| Browser only APIs | window, localStorage or screen size do not exist on the server | Read them inside useEffect after hydration |
| Invalid HTML nesting | A div inside a p, or a link inside a link, is repaired differently by the browser | Fix the markup so the parser keeps it as written |
| Browser extensions | Extensions insert elements before React hydrates | Test in a clean profile; usually not the site's fault |
What hydration is
Frameworks such as React Router render a page to HTML on the server or at build time, so the browser can show content before any JavaScript runs. When the JavaScript arrives, React runs the same components again in the browser and walks the existing HTML, attaching event handlers instead of rebuilding the page. React's documentation calls this hydrateRoot. Hydration only works if React's first browser render produces exactly the markup the server produced. When it does not, React reports a hydration mismatch.
What happens when it fails
In development React logs the mismatch with the text or attribute that differed. In production, depending on the version and the size of the difference, React may patch small text differences, or discard the server HTML for that part of the tree and render it again on the client. Visitors see a flash as content changes, layout can shift, and performance gains from server rendering are lost. In some cases event handlers attach to the wrong elements, so a button does not respond. React's minified production errors, such as error 418, point to the same problem.
When it matters
Hydration errors matter on any site that renders on the server or prerenders pages, which includes most modern React sites. They are more likely on pages that show times, counts, personalised greetings or anything based on screen size. They matter for search too, because a page whose content changes after load may be indexed in its first state. And they matter for trust: a menu that jumps or a price that flickers looks broken, even if it settles a second later.
Common mistakes
Formatting a date with the visitor's locale during render, so the server's English date becomes a different string in the browser. Checking typeof window inside render to choose different output, which guarantees a mismatch. Rendering a different layout for mobile in JavaScript rather than with CSS media queries. Nesting block elements inside paragraphs. Silencing the warning with suppressHydrationWarning everywhere, which hides real bugs. And reading a theme or a cart from localStorage during the first render instead of after it.
Where it shows up in OneCraft
OneCraft websites are React Router projects written as code. Every build runs a layout check that opens each prerendered page in headless Chromium at 375, 768 and 1280 pixels and fails the build on sideways overflow and on runtime or hydration errors, so a page that hydrates with a mismatch does not pass. In a chat edit, a change whose build fails is rolled back to where the turn started, and Let AI fix it sends the error back to the agent. Every change is a commit you can restore from Versions.
Questions people ask
How do I find which element caused a hydration error?
Run the site in development mode and open the browser console. React's message names the text or attribute that differed and often shows both versions. Compare the server HTML from View Source with the element after load. Times, ids and anything depending on the window are the usual suspects.
Is suppressHydrationWarning a fix?
Only for one element whose text is meant to differ, such as a timestamp. It tells React to ignore the mismatch on that element and does not apply to its children. Using it widely hides genuine bugs, so fix the cause instead and keep the attribute for the rare deliberate case.
Do hydration errors affect SEO?
They can. Search engines read the HTML the server sent, so if the page changes after hydration, the indexed version may not match what visitors see. Severe mismatches that make React re-render on the client also slow the page, which affects the Core Web Vitals that measure loading and layout shifts.
Why do I only see the error in production?
Development and production builds differ, and some causes only appear with real data, real time zones or a CDN in front of the site. Browser extensions that edit pages also trigger it for some visitors and not others. Reproduce it with the production build locally in a clean browser profile.
Can CSS cause a hydration error?
Not by itself, because CSS does not change the markup React compares. CSS is actually the safe way to show different layouts on mobile and desktop. Problems start when JavaScript decides which markup to render based on screen size during the first render, which the server cannot know.
Make one with websites
The button opens the generator with this use case already described. Change the wording to match your own.
Create a website with OneCraftRelated questions
- Static site vs server side renderingStatic site vs server side rendering: pages built once at build time against pages rendered on every request, compared on speed, hosting, fresh data and cost.
- What is a service worker?What is a service worker? A browser script that runs apart from the page, intercepts requests and caches files so a site loads fast and shows an offline page.
- What is JSON-LD?What is JSON-LD? Linked data in a script tag that describes a page to search engines: the format, the schema.org types a small business uses, and mistakes.
- What are Core Web Vitals?What are Core Web Vitals? Three measures of loading, responsiveness and visual stability, LCP, INP and CLS, with the thresholds Google uses and what moves them.
Written and checked by the OneCraft team. Last checked .