Bushra

Posted on Sep 15

Next.js Hydration Error: Why It Happens & How to Fix It (For Good)

#nextjs #react #hydration #webdev

If you’ve worked with Next.js, you’ve probably seen this warning pop up at least once:

Warning: Text content does not match server-rendered HTML.

The infamous Hydration Error.

The first time I saw it, I thought: “Wait, my app works… so why is this error screaming at me?”
And then, project after project, it kept showing up.

Turns out, it’s one of the most common hurdles for anyone moving from React to Next.js.
And the good news? Once you understand the why, fixing it becomes straightforward.

🔎 Why does this happen?

Hydration = connecting server-rendered HTML with React on the client.

If what the server outputs doesn’t exactly match what React expects → hydration error.
It’s not random. It’s just Next.js saying: “Hey, something’s different here.”

Usual suspects I faced:

Using window / document on the server (which doesn’t exist in SSR)
Values that change between renders (Math.random(), Date.now())
Conditional rendering behaving differently on server vs client
Third-party components that aren’t SSR-safe

✅ How I fixed it

Here are the solutions that worked every time:

1.Run browser-only code in useEffect

   // ❌ Wrong
   const width = window.innerWidth;

   // ✅ Correct
   const [width, setWidth] = useState<number | null>(null);
   useEffect(() => {
     setWidth(window.innerWidth);
   }, []);

2.Use dynamic imports for client-only components

   import dynamic from "next/dynamic";
   const Chart = dynamic(() => import("../components/Chart"), { ssr: false });

3.Keep initial render consistent
If you show placeholders/spinners, make sure they render the same on both server and client before React takes over.

4.Check your libraries
Not every npm package is built with SSR in mind. Use alternatives or load them dynamically.

5.Debug smart
Compare what’s rendered on the server vs client — that mismatch is where the error starts.

🚀 Best practices to avoid hydration errors

Predictable rendering only. Don’t use values that change between renders.
Separate SSR-safe vs client-only logic early. Think: Can this run on the server?
Leverage useEffect & dynamic imports. These are your go-to tools.
Be cautious with conditional rendering. Both server & client must agree on the initial output.
Test with production builds (next build && next start). Some hydration issues don’t show in dev mode.

💡 Takeaway

Hydration errors aren’t random bugs. They’re actually signals telling you something isn’t SSR-friendly.

Once you understand them, you’ll find your Next.js apps become more stable, predictable, and production-ready.

💬 Over to you

Have hydration errors ever driven you crazy?
How did you fix them? Or maybe… are you still fighting with them right now? 😅

Drop your story — let’s make this error a little less scary together.

DEV Community