Skip to content

[v4] Dashboard crashes with "Maximum update depth exceeded" on browser Back with cacheComponents (dev) #19570

Open

Description

@birdzai

Describe the Bug

With cacheComponents: true in next.config, pressing the browser Back button to return to the admin dashboard can crash the restored view with:

Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.

Next.js's error overlay appears and the dashboard does not render.

The stack ends in RenderNothingWhileHidden (@payloadcms/next/dist/adapters/UnmountWhenHidden), inside React's reappearLayoutEffects path, which runs when a hidden <Activity> boundary becomes visible again:

at dispatchSetState (react-dom-client.development.js)
at t1 (@payloadcms/next/dist/adapters/UnmountWhenHidden/index.js:42)   // setIsVisible(...) in the useLayoutEffect
at commitHookLayoutEffects
at reappearLayoutEffects
at recursivelyTraverseReappearLayoutEffects
... (reappearLayoutEffects / recursivelyTraverseReappearLayoutEffects repeated)
at commitLayoutEffectOnFiber

UnmountWhenHidden was added in #18702 (feat: support cache components) and first shipped in 4.0.0-beta.5. It still reproduces on 4.0.0-beta.7 and 4.0.0-beta.8. No project code appears in the stack.

Root cause (traced with instrumented React-DOM)

RenderNothingWhileHidden does useState(true) plus useLayoutEffect(() => { setIsVisible(true); return () => setIsVisible(false) }, []). When the Activity boundary hides, the cleanup sets isVisible=false, which unmounts the page subtree. When the page is shown again, the layout effect's setIsVisible(true) re-renders the page on the SyncLane.

We logged every suspension in React's throwException and every show/hide in RenderNothingWhileHidden during a crashing Back navigation (~26 cycles in ~720 ms, about 4 ms per cycle):

  1. The page is shown. A dashboard widget's server-rendered content is still pending (an RSC lazy chunk), so its host <div> suspends. This happens first at lane 0x20, then at lane 0x2 (sync).
  2. A synchronous render can't keep showing the previous UI, so the nearest <Suspense> boundary above commits its fallback. That hides the subtree.
  3. Hiding runs the cleanup (setIsVisible(false)). The page renders null, which doesn't suspend, so the subtree is revealed again.
  4. On reveal, setIsVisible(true) runs again. The widget content was discarded in step 3, so it suspends again. Back to step 2.

React stops this with "Maximum update depth exceeded". In every cycle the suspending fiber was the same host <div>, with this ancestry (minified names mapped from @payloadcms/ui/dist/exports/client/index.js):

div  <  WidgetContent (div.widget-content)  <  Widget (div.widget, dnd-kit draggable)
     <  DndContext  <  modular dashboard grid  <  …  <  DefaultTemplate
     <  …  <  RenderNothingWhileHidden

The loop needs widget content that is still pending when the page reappears, so the crash depends on timing. It was reliable for us when the dashboard's "Recently viewed" widget had several entries (a populated per-user recently-viewed preference). It did not reproduce with an empty preference, and we couldn't reproduce it in a blank template.

The trigger is the built-in Activity widget ("Recently viewed")

We narrowed it down in the same app:

  • Removing only the Activity widget stops the crash. With admin.dashboard.defaultLayout set to [welcome, collections], there were 0 crashes in 10 rounds. With the default layout, the same script crashed within 2 rounds every time.

  • The pending thenable is the widget's own server output. We logged every suspension in React's throwException during a crashing round. Each one in the loop is a pending Flight chunk whose _debugInfo names ActivityWidget:

    t=28755  lanes=0x4000  Back-navigation refetch (transition) renders the dashboard
    t=28830  lanes=0x20    pending chunk, _debugInfo: ActivityWidget   ← first suspension, non-transition
    t=28851  lanes=0x2     pending chunk, _debugInfo: ActivityWidget   ← then ~every 3ms, sync
    ...      (×25)
    t=28952  "Maximum update depth exceeded"
    
  • It's server data, not a client chunk. No _next/static/chunks requests were in flight during the loop. The only request on Back was the /admin?_rsc refetch. A Back round where ActivityWidget happened to be resolved in time did not crash.

Probable path, inferred from lanes and source: useDashboardLayout syncs the initialLayout prop into state with a plain effect: useEffect(() => { if (!isEditing) setCurrentLayout(initialLayout) }, [initialLayout]).

  1. The refetch transition commits the new initialLayout without waiting on the widget elements, because they're only stored in that prop, not rendered.
  2. The effect then renders them in a non-transition update (the 0x20 above).
  3. ActivityWidget's content is still streaming, so it suspends outside a transition.
  4. The Suspense boundary above the page shows its fallback, which hides the page, and the UnmountWhenHidden loop starts.

Making setCurrentLayout a transition fixes it (fix B below).

Fixes tested locally

We tested both candidate fixes in the same app (dev server, same data, same user) with a scripted loop: open Members from the dashboard, wait 2.5s, history.back(), then count animation frames with no visible .template-default for 1.5s. That's the same blank-frame measure as the existing cacheComponents e2e test.

Build Crashes Blank frames per dashboard Back
beta.8 unpatched every run, by round 2 n/a (crashes)
A: startTransition(() => setIsVisible(true)) in RenderNothingWhileHidden 0 / 10 0–11 (median 7)
B: startTransition(() => setCurrentLayout(initialLayout)) in useDashboardLayout 0 / 20 0 in all 20

Going Back to a list view (Pages → Posts → Back) showed 0 blank frames in all 8 rounds, both unpatched and with fix A.

Fix B is the one we'd propose. It stops the dashboard from rendering still-streaming widget content outside a transition, so nothing suspends on the sync path and UnmountWhenHidden never starts looping. Fix A also stops the crash, but it delays every reveal until after paint, which shows a blank admin for a few frames on Back. That's the regression the existing e2e test guards against.

RenderNothingWhileHidden will still loop if anything else under it suspends in a non-transition update. Fix B removes the trigger we found, not that general sensitivity.

Link to the code that reproduces this issue

No minimal reproduction yet. We could only trigger it in our own app, and these attempts on a blank beta.8 template (with cacheComponents, partialPrefetching, reactCompiler) did not crash:

  • the default dashboard with Activity, and a Recently-viewed list mirroring the 5 collections that trigger it in our app (including drafts and upload fields): 10 rounds clean, still clean with 150ms and 600ms of extra read latency per collection
  • 7 Recently-viewed cards on local uploads
  • a custom dashboard widget whose server component waits 1.5s: the fresh content swaps in after Back without ever hiding (26 rounds)
  • a beforeDashboard client component that use()s a promise created on popstate: it suspends on Back for ~1.7s but doesn't loop (10 rounds)

Because of that, the evidence below comes from the affected app itself: a suspension trace, a widget bisect, and a fix tested before and after. The fix is in a PR that I'll link here.

Reproduction Steps

  1. Payload 4.0.0-beta.8, with cacheComponents: true in next.config (we also have partialPrefetching: true).
  2. Run next dev and log in to /admin as a user whose dashboard "Recently viewed" widget has several entries from different collections.
  3. From the dashboard, open a collection (e.g. via a widget's "Show all …" link).
  4. Press the browser Back button. It may crash on the first Back. If it doesn't, repeat steps 3–4.

Reproduced in Chrome in dev mode only. Fix B above stops the crash in that same setup. A production build (next build + next start) did not crash in 6 round trips.

Which area(s) are affected?

area: ui, area: core (@payloadcms/next)

Environment Info

payload: 4.0.0-beta.8 (also beta.5, beta.7)
@payloadcms/next: 4.0.0-beta.8
next: 16.4.6 (Turbopack, dev)
react / react-dom: 19.3.1
node: 24.x
bun: 1.4.4
db: @payloadcms/db-postgres 4.0.0-beta.8
next.config: cacheComponents: true, partialPrefetching: true, reactCompiler: true
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions