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

Open
#19,570 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@birdzai is already working on this.

Since Nov 13, 2026.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
22/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
nextjs, react
Domain
frontend

Research direction

The loop is driven by RenderNothingWhileHidden in @payloadcms/next (adapters/UnmountWhenHidden), which sets visibility in a layout effect, and by useDashboardLayout, which syncs initialLayout with a plain effect. Start by reading both, then reproduce the Back navigation on the dashboard with cacheComponents enabled. Done means no 'Maximum update depth exceeded' on Back and the cacheComponents e2e blank-frame test still passing. Linked PR #19571 already covers this, so check it first.

Written by the indexing model from the issue text.

Description

area: core (`@payloadcms/next`) area: ui Bug Payload OSS
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
Dominant language
TypeScript
Stars
45.8k
Forks
4.4k
Avg merge
2d 16h
Merged PRs (30d)
251

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from payloadcms/payload

All issues in payloadcms/payload

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.