The Root Cause of Hydration Mismatch Errors in SSR

Hydration completed but contains mismatches.💥

SSR (Server-Side Rendering) is one of the biggest advantages of modern frameworks—fast loading, SEO-friendliness, and strong initial render performance. But there’s a side effect: Hydration Mismatch.
If you’ve seen a warning like this in a Vue or Nuxt project, you’re not alone:

Hydration completed but contains mismatches.

This looks mysterious but it’s quite logical. In this post, we’ll unpack what “hydration” actually is, why “mismatch” happens, and how to prevent it.

What Is Hydration?

When an SSR page loads, the flow is:

1. Server Render: Nuxt generates HTML and sends it to the browser.
2. Client Hydration: The browser receives the HTML, bootstraps the Vue app, and recreates the same virtual DOM tree.
3. Vue compares the HTML and the virtual DOM—if they’re identical, hydration succeeds.

In short: SSR HTML ≠ Client render output → Hydration Mismatch.

The Most Common Causes

1) Time- or browser-dependent code

<p>{{ new Date().toLocaleTimeString() }}</p>

✅ Fix: Move browser-only code into onMounted().

<script setup>
import { ref, onMounted } from 'vue'
const time = ref('')
onMounted(() => (time.value = new Date().toLocaleTimeString()))
</script>

2) Random values

<p>{{ Math.random() }}</p>

✅ Fix: Generate the random value on the server and pass it as a prop, or generate it only on the client.

3) Accessing window or document

const width = window.innerWidth // ❌ SSR crash

✅ Fix:

if (process.client) {
  const width = window.innerWidth
}

onMounted(() => {
  console.log(window.innerWidth)
})

4) Conditional render differences

<div v-if="isClient">Client Render</div>

✅ Fix: Keep the same initial state across SSR and client. Use useState() if needed.

5) Async data inconsistencies

✅ Fix: Always provide a unique key to each useAsyncData call.

await useAsyncData('posts', () => $fetch('/api/posts'))

Understanding the Hydration Flow

1. HTML is generated during SSR.
2. The Vue app boots on the client.
3. Vue compares SSR HTML with its client render.
4. On difference, it logs a hydration mismatch warning.
5. Vue then rebuilds parts of the DOM (even if you don’t see a difference), incurring a perf cost.

Helpful Tools for Diagnosis

• Detailed console.warn messages: Vue often points to the problematic node.
• nuxt dev --debug mode: Highlights hydration diffs line-by-line.
• Vue Devtools: Inspect differences between SSR HTML and client render.

Fix Matrix

Bonus: isHydrating & onHydrated

const nuxtApp = useNuxtApp()
nuxtApp.hook('app:hydrated', () => {
  console.log('Hydration completed!')
})

Hydration vs Suspense

✅ Fix: Either set suspensible: false on async components under Suspense, or guard with v-if="hydrated".

Conclusion

In short:

• window, document, Math.random(), Date() = handle with care.
• Keep SSR and client state aligned.
• onMounted and process.client are your best friends.