React Error #421: This Suspense boundary received an update before it finished hydrating

What causes this error

When SSR HTML is being hydrated by the client, React replays the render to attach event listeners. If a state update fires during that window (from a useEffect, a same-tick setState, or a router event), and that update reaches a Suspense boundary, React can't safely apply it - hydration must complete first. React throws #421 to say: this update arrived too early.

How to fix it

1. 01

   step 1

   Find the update source

   The trace points to the Suspense boundary, but the bug is wherever the update came from. Look for setState calls in render bodies, useLayoutEffect that fires before hydration completes, or router-event subscriptions that call setState immediately on mount.

   // Common offenders
   function Bad() {
     const router = useRouter()
     setSomething(router.path)  // setState during render
     return <Suspense>...</Suspense>
   }

   Copy
2. 02

   step 2

   Move client-only state into useEffect

   If the value comes from window, localStorage, or any browser-only API, it cannot be set during SSR. Initialize with the SSR default, then update in useEffect after mount.

   function ClientOnly() {
     const [width, setWidth] = useState(0)  // SSR default
     useEffect(() => {
       setWidth(window.innerWidth)
       const handler = () => setWidth(window.innerWidth)
       window.addEventListener('resize', handler)
       return () => window.removeEventListener('resize', handler)
     }, [])
     return <p>{width}</p>
   }

   Copy
3. 03

   step 3

   Wrap router-driven updates in startTransition

   If you subscribe to router events that fire immediately on mount (Next.js App Router does this), the resulting setState may race hydration. Wrap in startTransition so React defers it until after hydration.

   import { startTransition, useEffect } from 'react'
   
   function Tracker() {
     const path = usePathname()
     useEffect(() => {
       startTransition(() => {
         analytics.track('pageview', path)
       })
     }, [path])
   }

   Copy
4. 04

   step 4

   Remove setState in render bodies

   Calling setState during render schedules an update synchronously. During hydration, this update can reach a Suspense boundary before hydration completes. Move to useEffect or compute the value derived from props directly.

   // Bad - setState in render
   function Bad({ user }) {
     const [name, setName] = useState('')
     if (user && !name) setName(user.name)  // hits #421 during hydration
     return <Suspense>...</Suspense>
   }
   
   // Good - derive directly
   function Good({ user }) {
     const name = user?.name ?? ''
     return <Suspense>...</Suspense>
   }

   Copy
5. 05

   step 5

   Check third-party providers that mount listeners early

   Auth providers, analytics SDKs, and feature-flag clients often fire their first event in their constructor or top-level useEffect. If these trigger setState in your tree mid-hydration, you'll see #421. Lazy-init or wrap their callbacks in startTransition.

   useEffect(() => {
     const sub = featureFlags.subscribe((flag) => {
       startTransition(() => setFlag(flag))
     })
     return () => sub.unsubscribe()
   }, [])

   Copy