How to debug hydration mismatch warning in production that don't exist in dev/preview
I've been working with other frameworks for a while and decided to put my hands in Nuxt for the first time.
For now I just a built a simple app with authentication flow and when I deployed to production, after visiting the home page I get the "Hydration completed but contains mismatches." warning in production. However, when in dev mode or in preview, I don't get anything. TBH this is a big red flag for me, I've never experienced any issues in other frameworks that would allow something so trivial to happen in production and not in development. How could I debug this?
Since it's still a small app, I reviewed all implementation and I'm using all SSR friendly (useFetch, useSTate etc)
3 Replies
Hi @ianzovisk. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
Hydration mismatch warnings in Nuxt typically indicate that the HTML rendered on the server does not match what the client-side JavaScript expects. It's unusual for these warnings to appear only in production and not in development or preview, but there are some known causes and debugging strategies you can follow.
Common Causes
- Inconsistent Data: If your data differs between server and client (e.g., using
Math.random(), time-based values, or mutating props), this can cause mismatches. Always use SSR-friendly composables like useFetch, useAsyncData, and useState to ensure data consistency between server and client.
- Browser-only APIs: Using browser-specific APIs (like localStorage or window) during SSR will cause mismatches, since these are not available on the server.
- Conditional Rendering: Rendering based on client-only state (like window size) during SSR can lead to mismatches.
- Third-party Libraries: Some libraries may behave differently in production builds, especially if they manipulate the DOM or rely on browser APIs.
- Dynamic Content: Content that changes based on time or other non-deterministic factors can cause mismatches if not handled properly.
You can find detailed examples and solutions for these issues in the Nuxt documentation:
- Common reasons for hydration mismatches
- SSR-friendly state management
Debugging Steps
1. Check Console Warnings in Development: Normally, Vue logs hydration mismatch warnings in the browser console during development. If you don't see them in dev/preview, but do in production, it may be due to differences in your build or environment configuration. Double-check that your dev and production environments are as similar as possible (e.g., same environment variables, SSR settings, etc.) Development Console Warnings.
2. Review Data Flow: Ensure that all data used for rendering is fetched and provided in an SSR-friendly way. Avoid mutating props directly, as this can cause inconsistencies between server and client. For example, mutating a prop array with .shift() will cause hydration issues; instead, create a local copy before mutating it [Nuxt 3 Hydration text mismatch in ... error when using shift()].
3. Check for Production-Only Code Paths: Sometimes, code behaves differently in production due to minification, tree-shaking, or different environment variables. Review any code that might be conditionally executed only in production.
4. Disable Third-party Modules: If you are using modules like PWA or analytics, try disabling them to see if the issue persists. Some modules can introduce hydration mismatches in production builds [Adding '@vite-pwa/nuxt' to nuxt 3 project causes hydration errors].
5. SSR Debugging Tools: In recent Nuxt versions, there are improvements to help debug SSR issues, such as prompts or links to open the page with SSR disabled for debugging (in dev mode). While this is more helpful in development, it can sometimes help you isolate the issue [feat(nuxt): add ssr debug prompt with link].
Summary
- Double-check your data sources and avoid mutating props.
- Ensure all rendering logic is SSR-safe and deterministic.
- Compare your dev and production environments for differences.
- Use SSR-friendly composables and avoid browser-only APIs in server context.
If the issue persists and you cannot reproduce it in development, try to isolate the minimal code that causes the mismatch and incrementally add features until the warning appears. This can help pinpoint the root cause.
For more details and examples, see the Nuxt documentation on hydration best practices.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@235528794805501962> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
This is impossible to debug without knowing more, but typically think of the differences between your local machine and your prod server.
Differnt Timezone -> date difference between server/client
etc