Diagnosing Nuxt 3 SSR Hydration Mismatches with useFetch

Recognizable condition

When a Nuxt 3 page loads, you see a console warning similar to "Hydration completed but contains mismatches", and the UI may flicker or show missing content after the initial HTML is painted. The server rendered one version of the markup; Vue's client-side hydration produced another and had to patch or discard parts of the DOM.

Common causes and diagnostic clues

Ordered checks

1. Verify placement. Open the component that uses useFetch and ensure the call is inside setup() (or a composable invoked from setup()) with no if (process.client) wrapper around it.
2. Check serializability. Confirm the value returned from useFetch contains only JSON-serializable types — no window, document, DOM nodes, class instances, or functions. Inspect the returned value in the browser console; non-plain objects are a red flag because Nuxt embeds the payload in the page as JSON.
3. Compare server and client payloads. In Chrome DevTools, copy the root element's outer HTML before interacting with the page — that is the server-rendered snapshot. Then, after hydration, use the Nuxt DevTools Hydration panel (or Vue DevTools) to capture the client-rendered DOM and diff the two. The first differing node usually points at the responsible component.

Fixes tied to findings

Move data fetching into a shared composable using useAsyncData. This guarantees the call runs on the server and that the result is serialized into the payload for the client to reuse, instead of refetching with possibly different results:

// composables/usePosts.js
export function usePosts () {
  return useAsyncData('posts', () => $fetch('/api/posts'))
}

// inside a page or component's script setup block:
// const { data: posts } = usePosts()

Guard client-only accesses. If you need browser-specific APIs, wrap them in if (process.client) and keep the fetched data out of that block:

if (process.client) {
  // safe to use window.innerWidth etc.
  const width = window.innerWidth
}

Key list items with stable IDs. When rendering arrays from fetched data, bind a unique, stable key (for example :key="item.id") so Vue does not reorder or reuse elements during hydration.

Force eager hydration for a problematic component. If you use lazy-hydration wrappers, temporarily render the suspect component eagerly (for example via Nuxt's delayed-hydration controls or by removing the lazy wrapper) to see whether the mismatch is timing-related.

Escalation criteria

If the mismatch warning persists after the checks and fixes above:

1. Launch Nuxt DevTools (npx nuxi devtools enable, then restart the dev server) and open the Hydration panel to see the exact diff.
2. Inspect the Nitro server logs (dev terminal output, or your hosting platform's log stream in production) for errors thrown while useFetch resolved on the server.
3. As a temporary workaround, set ssr: false for the affected route via routeRules in nuxt.config.ts to render that page purely on the client while you investigate. Do not disable SSR globally — it removes SEO and first-paint benefits for content-rich pages.
4. If the data does not change per request, consider prerendering the route (routeRules: { '/': { prerender: true } }) so server and client always share the same static payload.

Limitations and verification

These steps cover the most common hydration mismatches caused by useFetch. They do not address third-party plugins that mutate the DOM outside Vue's reconciliation, or custom directives that modify elements after server render. To verify a fix:

• Run the dev server with Nuxt DevTools and confirm the Hydration panel shows no warnings after a full page reload.
• Build with nuxt build and start with nuxt start; view the page source and confirm the expected data appears in the initial HTML.
• Deploy to a preview environment and run Lighthouse; confirm SEO-critical content is present in the loaded HTML, not only after JavaScript executes.