Admin RootLayout passes a server-made viewport element into the client DocumentRoot's <head> — duplicate tag, and it can suspend <head> and break hydration in Next dev

Open
#19,697 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@lx3133584 is already working on this.

Since Nov 18, 2026.

  • #19706 by @lx3133584 — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
35/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Stale
Domain
frontend

Research direction

Read packages/ui/src/layouts/Root/index.tsx and packages/ui/src/layouts/Root/DocumentRoot.tsx, then compare them with packages/next/src/adapters/viewport.ts. The issue proposes removing the viewport prop and its getViewportMeta call because the Next metadata adapter already emits the tag. Confirm the admin has one viewport meta tag and check that the reported development hydration failure is resolved; linked pull request #19706 is already open.

Written by the indexing model from the issue text.

Description

Bug
Describe the Bug

@payloadcms/ui's server RootLayout creates a <meta name="viewport"> React element on the server and passes it as the viewport prop into the client DocumentRoot, which renders it inside <head>:

This causes two problems:

1. The tag is emitted twice. @payloadcms/next's generateViewport adapter (packages/next/src/adapters/viewport.ts) already emits the identical viewport meta through Next's metadata API (same getNextViewport logic, including maximumScale: 1 for iPhone user agents), so a standard admin layout ends up with two <meta name="viewport"> tags.

2. In Next.js 16 development it can suspend <head> during hydration, which trips a React bug and fails hydration of the whole admin. Because the element is created in a server component and rendered by a client component, Next's dev server streams its React debug rows (owner/stack) separately, over the dev websocket. When those rows arrive after hydration has already started, the element is still a blocked Flight chunk, so <head> suspends. React then replays the head fiber, and due to https://github.com/react/react/issues/37551 the replay overwrites the single saved hydration position outside <head> with a node inside <head>. <body> then hydrates against <head>'s nodes: "Hydration failed because the server rendered HTML didn't match the client", and the whole document is client-rendered.

Whether it fires depends on dev-server timing. In one project, a long-running dev server failed almost every load of some admin views (collection create/edit) while other views never failed; a freshly restarted server never failed at all. Production builds have no debug channel and are unaffected.

Reproduction Steps / Evidence

Observed on Payload 4.0.0-beta.6 (@payloadcms/[email protected]), Next.js 16.4.6, react/react-dom 19.3.1, dev server (next dev):

  • Instrumenting React's singleton hydration path in the browser showed every failing load entering <head> twice, with the second entry overwriting the saved cursor with a node inside <head> — the exact mechanism of react/react#37551. Clean loads entered <head> once.
  • Serving the same pages with the viewport prop removed from RootLayout: 0/6 failing loads, against 3/3 failing unmodified at the same moment.
  • With the prop removed, exactly one <meta name="viewport"> remains (the one from generateViewport), and the admin behaves identically.
Suggested fix

Drop the viewport prop from RootLayout/DocumentRoot (and the getViewportMeta call), since the Next adapter's generateViewport already emits the same tag. DocumentRoot's own doc comment already points this way ("adapters with router-managed metadata supply it through head"), so an adapter without router-managed viewport metadata could pass it via the existing head prop instead. This removes the duplicate tag and the dev-only <head> suspension regardless of when the React bug is fixed.

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.