How to fix React hydration errors

Why React hydration mismatches happen in server-rendered apps, how to read the error, and reliable fixes for dates, browser-only code, invalid HTML and extensions.

By the UK Technology Hub teamPublished 4 minute read

The short answer

A hydration error means the HTML React rendered on the server doesn't match what it renders in the browser during hydration. Common causes are values that differ between server and client, such as dates, random numbers or browser-only data, invalid HTML nesting, and browser extensions changing the page. Make the first client render match the server, move browser-only logic into effects or client-only components and fix invalid markup.

Server-side rendering makes React apps faster and more search-friendly: the server sends ready-made HTML, then React "hydrates" it in the browser, attaching event handlers and taking over. Hydration expects the browser render to match the server HTML. When it doesn't, React reports a hydration error and may re-render parts of the page.

Reading the error

Modern React and frameworks like Next.js show which element and text differ between server and client. Look for:

  • The component name.
  • The expected server content versus client content.
  • Whether the difference is in text, attributes or structure.

Common causes and fixes

1. Dates and times

Rendering the current time or formatting dates with the user's locale gives different results on the server and in the browser.

Fix: render a stable value on the server, such as an ISO date, then update to a local format after mount in an effect, or render times only on the client.

2. Random values and IDs

Math.random or generated IDs differ between renders.

Fix: use React's useId hook for IDs, and generate random values after mount if needed.

3. Browser-only APIs

Code that reads window, localStorage, screen size or user agent during render runs differently on the server, where those don't exist.

Fix: read browser-only data in useEffect, after hydration, or render those parts only on the client using your framework's client-only options.

4. Conditional rendering based on the client

Showing different content for logged-in users, themes or screen sizes based on browser data creates mismatches.

Fix: render a consistent placeholder first, then update after mount; or determine the state on the server using cookies or headers.

5. Invalid HTML nesting

Browsers automatically correct invalid HTML, such as a div inside a p, or nested links. The corrected DOM no longer matches React's expectations.

Fix: use valid nesting; check component output for block elements inside paragraphs and interactive elements inside each other.

6. Browser extensions

Extensions like translators, password managers and ad blockers can modify the page before React hydrates.

Fix: test in a private window without extensions. If only extensions cause it, your code may be fine, though some attributes on the html or body elements may be safely ignored.

7. Data differences

Server and client fetching different data, or caching differently, creates mismatches.

Fix: pass server-fetched data to the client rather than refetching during the first render.

About suppressing warnings

React allows suppressing hydration warnings for specific elements, such as timestamps. Use this sparingly and only when a mismatch is expected and harmless. Fix underlying causes wherever possible.

Why it matters

Hydration mismatches can cause flickering, lost interactivity, slower performance and inconsistent content. Fixing them improves user experience and reliability.

Debugging tips

  1. Reproduce the error in development, which gives more detail.
  2. Compare the server HTML (view source) with the rendered DOM.
  3. Comment out components to isolate the source.
  4. Check recent changes involving dates, browser APIs or conditional rendering.

Client-side effects that aren't cleaned up can cause memory leaks; see our guide to fixing JavaScript memory leaks. API calls failing in the browser may be CORS problems; see our guide to fixing CORS errors.

Preventing hydration errors in new code

  • Keep render logic pure: no reading browser APIs, dates or random values during render.
  • Put browser-only work in effects or client components.
  • Use your framework's recommended patterns for data fetching on the server.
  • Validate HTML structure in components, especially lists, tables and paragraphs.
  • Add end-to-end tests that load server-rendered pages and check for console errors.

Third-party scripts

Analytics, chat widgets and A/B testing tools sometimes change the DOM before React hydrates. Load them after hydration or in ways that don't modify server-rendered elements React controls.

Keep framework versions current

Framework updates often improve hydration error messages and handling. Keeping React and your framework reasonably current makes debugging easier.

How we help

Our web app development team builds and debugs server-rendered React applications. Our web development team optimises rendering strategies for speed and SEO, and our app development service shares reliable patterns across web and mobile.

Frequently asked questions

What is hydration in React?

The process where React attaches event handlers and takes over server-rendered HTML in the browser.

Why do dates cause hydration errors?

The server and browser often have different time zones and locales, so formatted dates differ.

Should I disable server rendering to avoid hydration errors?

Usually not. Fix the mismatch instead, so you keep the speed and SEO benefits of server rendering.

This guide is general information, not legal, tax or financial advice, and details such as prices, features and rules can change. Product and company names mentioned are trademarks of their respective owners and are used only to identify those products; UK Technology Hub is not affiliated with or endorsed by them.

Related guides

How to fix CORS errors: a practical guide

What CORS errors actually mean, why they happen, and how to fix them correctly on the server, including preflight requests, credentials and common mistakes.

How to find and fix JavaScript memory leaks

What memory leaks look like in web apps, the most common causes, how to find them with browser developer tools, and patterns that prevent them.

How to fix the WordPress white screen of death

A calm, step-by-step guide to diagnosing and fixing a blank white WordPress page, from recovery mode and debug logs to plugins, themes and memory limits.

All bug fixes & troubleshooting guides