1---
2title: Understand and Fix SSR Hydration Mismatches
3impact: HIGH
4impactDescription: Hydration mismatches cause visual flickering, performance loss, and broken functionality
5type: gotcha
6tags: [vue3, ssr, hydration, debugging, nuxt, server-side-rendering]
7---
8 
9# Understand and Fix SSR Hydration Mismatches
10 
11**Impact: HIGH** - Hydration mismatches occur when the HTML rendered on the client differs from what the server rendered. Vue attempts to recover by discarding and re-rendering mismatched nodes, causing performance degradation, visual flickering, and potentially broken event handlers.
12 
13Understanding the common causes helps you prevent and debug these issues effectively.
14 
15## Task Checklist
16 
17- [ ] Validate HTML structure for proper nesting (no div in p, no nested a tags)
18- [ ] Move random value generation to onMounted or use seeded randoms
19- [ ] Format dates/times on client side only
20- [ ] Use `data-allow-mismatch` (Vue 3.5+) for intentional mismatches
21- [ ] Check for browser-modified HTML in dev tools
22 
23## Cause 1: Invalid HTML Nesting
24 
25Browsers auto-correct invalid HTML, creating different DOM than Vue expects.
26 
27**Incorrect:**
28```vue
29<template>
30  <!-- WRONG: <div> cannot be inside <p> -->
31  <p>
32    <div>This will break hydration</div>
33  </p>
34 
35  <!-- WRONG: <a> cannot be inside <a> -->
36  <a href="/parent">
37    <a href="/child">Nested link</a>
38  </a>
39 
40  <!-- WRONG: Block elements in inline elements -->
41  <span>
42    <div>Block in inline</div>
43  </span>
44</template>
45```
46 
47Browser converts the first example to:
48```html
49<p></p>
50<div>This will break hydration</div>
51<p></p>
52```
53 
54**Correct:**
55```vue
56<template>
57  <!-- CORRECT: Use appropriate nesting -->
58  <div>
59    <div>This works fine</div>
60  </div>
61 
62  <!-- CORRECT: Single link with event handling -->
63  <a href="/parent" @click="handleParentClick">
64    <span @click.stop="handleChildClick">Nested action</span>
65  </a>
66 
67  <!-- CORRECT: Block element wrapper -->
68  <div>
69    <div>Block in block</div>
70  </div>
71</template>
72```
73 
74## Cause 2: Random Values in Render
75 
76Server and client generate different random values.
77 
78**Incorrect:**
79```vue
80<template>
81  <!-- WRONG: Different ID on server vs client -->
82  <div :id="'field-' + Math.random()">
83    Form field
84  </div>
85 
86  <!-- WRONG: Random order differs -->
87  <div v-for="item in shuffledItems" :key="item.id">
88    {{ item.name }}
89  </div>
90</template>
91 
92<script setup>
93import { computed } from 'vue'
94 
95const items = [/* ... */]
96 
97// WRONG: Random shuffle runs differently on server and client
98const shuffledItems = computed(() =>
99  [...items].sort(() => Math.random() - 0.5)
100)
101</script>
102```
103 
104**Correct - Client-Only Random:**
105```vue
106<template>
107  <div :id="fieldId">
108    Form field
109  </div>
110 
111  <div v-for="item in displayItems" :key="item.id">
112    {{ item.name }}
113  </div>
114</template>
115 
116<script setup>
117import { ref, onMounted } from 'vue'
118 
119const items = [/* ... */]
120 
121// CORRECT: Start with deterministic value
122const fieldId = ref('field-default')
123const displayItems = ref(items) // Original order on server
124 
125onMounted(() => {
126  // Randomize only on client
127  fieldId.value = 'field-' + Math.random().toString(36).slice(2)
128  displayItems.value = [...items].sort(() => Math.random() - 0.5)
129})
130</script>
131```
132 
133**Correct - Seeded Random:**
134```javascript
135// utils/seededRandom.js
136export function createSeededRandom(seed) {
137  return function() {
138    seed = (seed * 9301 + 49297) % 233280
139    return seed / 233280
140  }
141}
142 
143// Use same seed on server and client
144const seed = 12345 // Could be based on user ID, page, etc.
145const random = createSeededRandom(seed)
146```
147 
148## Cause 3: Timezone and Date Differences
149 
150Server may be in different timezone than client.
151 
152**Incorrect:**
153```vue
154<template>
155  <!-- WRONG: Server time != client time -->
156  <span>{{ new Date().toLocaleTimeString() }}</span>
157 
158  <!-- WRONG: Server formats dates in server's timezone -->
159  <span>{{ formatDate(article.createdAt) }}</span>
160</template>
161 
162<script setup>
163function formatDate(date) {
164  return new Date(date).toLocaleDateString()
165}
166</script>
167```
168 
169**Correct:**
170```vue
171<template>
172  <!-- CORRECT: Render placeholder, update on client -->
173  <span>{{ displayTime || 'Loading...' }}</span>
174 
175  <!-- CORRECT: Use UTC or defer to client -->
176  <span>{{ formattedDate }}</span>
177</template>
178 
179<script setup>
180import { ref, computed, onMounted } from 'vue'
181 
182const props = defineProps(['article'])
183const displayTime = ref(null)
184const isClient = ref(false)
185 
186onMounted(() => {
187  displayTime.value = new Date().toLocaleTimeString()
188  isClient.value = true
189})
190 
191// CORRECT: Server renders UTC, client converts to local
192const formattedDate = computed(() => {
193  if (!props.article?.createdAt) return ''
194 
195  if (isClient.value) {
196    // Client: user's local timezone
197    return new Date(props.article.createdAt).toLocaleDateString()
198  } else {
199    // Server: consistent UTC format
200    return new Date(props.article.createdAt).toISOString().split('T')[0]
201  }
202})
203</script>
204```
205 
206## Cause 4: Browser Extensions and Modifications
207 
208Browser extensions can inject content into the DOM.
209 
210**Mitigation:**
211```vue
212<template>
213  <!-- Use data-allow-mismatch for areas extensions might modify -->
214  <head data-allow-mismatch>
215    <title>{{ pageTitle }}</title>
216  </head>
217</template>
218```
219 
220## Vue 3.5+ Suppressing Intentional Mismatches
221 
222```vue
223<template>
224  <!-- Suppress specific mismatch types -->
225  <div data-allow-mismatch="text">
226    {{ clientOnlyText }}
227  </div>
228 
229  <!-- Suppress all mismatches for this element -->
230  <div data-allow-mismatch>
231    <ComplexClientComponent />
232  </div>
233</template>
234```
235 
236Valid `data-allow-mismatch` values:
237- `text` - Text content mismatches
238- `children` - Child element mismatches
239- `class` - Class attribute mismatches
240- `style` - Style attribute mismatches
241- `attribute` - Other attribute mismatches
242- (no value) - All mismatches
243 
244## Debugging Hydration Mismatches
245 
246```javascript
247// Enable detailed hydration mismatch warnings in development
248// vite.config.js
249export default {
250  define: {
251    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: true
252  }
253}
254```
255 
256```vue
257<script setup>
258import { onMounted } from 'vue'
259 
260// Debug: Compare server HTML with client expectation
261onMounted(() => {
262  const serverHTML = document.getElementById('app').innerHTML
263  console.log('Server rendered:', serverHTML)
264})
265</script>
266```
267 
268## Common Error Messages
269 
270| Error | Likely Cause |
271|-------|--------------|
272| "Hydration text content mismatch" | Different text on server/client (dates, random) |
273| "Hydration children mismatch" | Invalid HTML nesting, conditional rendering |
274| "Hydration attribute mismatch" | Dynamic attributes with different values |
275| "Hydration node mismatch" | Completely different elements rendered |
276 
277## Reference
278- [Vue.js SSR Guide - Hydration Mismatch](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch)
279- [Nuxt Hydration Best Practices](https://nuxt.com/docs/guide/best-practices/hydration)
280- [data-allow-mismatch RFC](https://github.com/vuejs/core/pull/9562)
281