What Causes Nuxt Hydration Mismatches and How to Fix Them

Hydration mismatches in Nuxt occur when the HTML rendered on the server differs from what Vue produces on the client during JavaScript initialisation. Because Nuxt runs the same component twice — once in Node on the server and once in the browser — any value that depends on the environment, such as random outputs, dates, or localStorage, can trigger a mismatch. The bug can range from a barely noticeable flicker to broken interactivity, as Vue may discard and rebuild DOM nodes that users have already interacted with. Developers can resolve most cases using onMounted to defer client-only values, the ClientOnly wrapper component, or the data-allow-mismatch attribute for intentional differences. The guidance is written against Nuxt 4.x but also applies to Nuxt 3 running in compatibilityVersion 4 mode.