Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

React says a Suspense boundary was updated before it finished hydrating

ErrorThis Suspense boundary received an update before it finished hydrating.

Short answer

The server HTML and the first client render of that boundary did not agree, or something changed state before hydration ended, so React cannot reuse the server HTML cleanly. Find the browser-only code in the render, move it into an effect or a client-only dynamic import, and give stores a stable server snapshot.

  • Applies to React 19, Next.js 15, Next.js 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find which component sits inside the boundary named in the stack, then search it for code that reads the browser or changes with time.

    grep -rnE "typeof window|window\.|localStorage|Date\.now|Math\.random" app components
  2. 2Match what you see, then jump to its fix

    1. 1The component checks typeof window or uses window.matchMedia, localStorage or the current time while rendering.The render reads browser-only valuesFix
    2. 2The component is loaded with next/dynamic and needs window, a canvas or a browser SDK.A client-only widget is server-rendered inside a Suspense boundaryFix
    3. 3The boundary holds a component that reads a global store through useSyncExternalStore.An external store returns different data on server and clientFix

What does the error look like?

  • This Suspense boundary received an update before it finished hydrating.
  • The warning appears around a component loaded with next/dynamic

Cause 1 of 3

The render reads browser-only values

1Check

React expects the first client render to match the server HTML. Its docs name typeof window checks, browser-only APIs and different data on server and client as mismatch sources.

grep -rnE "typeof window|matchMedia|localStorage" app components

2Fix

Render the same output at first, then switch after mount. The React docs show an isClient state set in an effect.

'use client'
import { useEffect, useState } from 'react'

export default function Banner() {
  const [isClient, setIsClient] = useState(false)
  useEffect(() => setIsClient(true), [])
  return <p>{isClient ? 'Is Client' : 'Is Server'}</p>
}

3Verify

Reload the page with the console open: the hydration message should not return.

npm run build && npm run start

Confirmed by react.dev

Did this fix it?

Cause 2 of 3

A client-only widget is server-rendered inside a Suspense boundary

1Check

Client components are prerendered on the server by default when loaded with next/dynamic or React.lazy. If the component cannot render on the server, the server and client output differ.

grep -rn "dynamic(" app components

2Fix

Turn off prerendering for it with ssr: false. The docs allow this only inside a Client Component, and you get an error if you use it in a Server Component.

'use client'
import dynamic from 'next/dynamic'

const Map = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>,
})

3Verify

Load the page and confirm the loading text shows, then the widget, with a clean console.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

An external store returns different data on server and client

1Check

React requires getServerSnapshot to return the same data on the first client render as on the server. A store with live data on the client and empty data on the server breaks this.

grep -rn "useSyncExternalStore" app components lib

2Fix

Pass the server's data to the client and return it from getServerSnapshot, or omit the argument to force client rendering for that part.

const value = useSyncExternalStore(
  store.subscribe,
  store.getSnapshot,
  store.getServerSnapshot
)

3Verify

Reload the page: the server HTML and the first client value should match.

npm run build && npm run start

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Keep the first client render identical to the server render; read browser values after mount.
  • Load widgets that need the browser with ssr: false inside a Client Component.
  • Do not hide the problem with suppressHydrationWarning: the React docs call it an escape hatch for one level only.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

next/link throws React.Children.only on its children

Error: React.Children.only expected to receive a single React element child.

React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.