Error: Hydration failed because the initial UI does not match what was rendered on the server
Most likely cause: Code that produces different output on server versus browser, such as using Date, Math.random, window, or localStorage directly in a component
Try first: Check the browser console for the exact mismatched element
Likely causes
- Code that produces different output on server versus browser, such as using Date, Math.random, window, or localStorage directly in a componentmost likely
- Browser extensions or third-party scripts altering the DOM before React hydratespossible
- Missing or incorrect use of dynamic imports or client-only components in a framework like Next.jspossible
How to fix it
Check the browser console for the exact mismatched elementSafe
Open DevTools (F12), go to the Console tab, and look for the line that shows which HTML tag or text differs between server and client.
Add suppressHydrationWarning to the differing elementChanges settings
In your React component, add the attribute suppressHydrationWarning={true} to the tag that is causing the mismatch. This tells React to ignore the difference for that element only.
Move browser-only code inside useEffectChanges settings
Wrap any code that uses window, document, or other browser APIs inside a useEffect hook so it only runs after the page loads in the browser.
If that didn't fix it
Search the component tree for any direct use of Date.now, Math.random, or similar values and move them inside a useEffect or mark the component as client-only with 'use client'.
When to see a technician
If the mismatch occurs in a production Next.js or React app and you cannot locate the offending component, ask a web developer familiar with server-side rendering.
Quick answers
- What does Error: Hydration failed because the initial UI does not match what was rendered on the server mean?
- This React error happens when the HTML built on the server looks different from what the browser tries to render on the client side, breaking the 'hydration' step that makes the page interactive.
- What causes Error: Hydration failed because the initial UI does not match what was rendered on the server?
- Code that produces different output on server versus browser, such as using Date, Math.random, window, or localStorage directly in a component. (most likely) Browser extensions or third-party scripts altering the DOM before React hydrates. (possible) Missing or incorrect use of dynamic imports or client-only components in a framework like Next.js. (possible)
- How do I fix Error: Hydration failed because the initial UI does not match what was rendered on the server?
- Try these in order, safest first: 1. Check the browser console for the exact mismatched element. 2. Add suppressHydrationWarning to the differing element. 3. Move browser-only code inside useEffect.
- What if that didn't fix it?
- Search the component tree for any direct use of Date.now, Math.random, or similar values and move them inside a useEffect or mark the component as client-only with 'use client'.
- When should I see a technician?
- If the mismatch occurs in a production Next.js or React app and you cannot locate the offending component, ask a web developer familiar with server-side rendering.