nextjs - ✅(Solved) Fix [v16.2+] Router state header was sent but could not be parsed on soft navigation with dynamic rendering [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#92907Fetched 2026-04-17 08:25:38
View on GitHub
Comments
0
Participants
1
Timeline
6
Reactions
6
Author
Participants
Timeline (top)
labeled ×3issue_type_added ×1renamed ×1subscribed ×1

Error Message

⨯ Error: The router state header was sent but could not be parsed. at ignore-listed frames

Root Cause

The issue is latent until a new deployment is made, because that is when the server version changes while clients still carry stale 16.1 router state. Dynamic routes/layouts are more likely to trigger this path because they always go to the server for RSC payloads, whereas fully static pages may be served from cache without header validation.

PR fix notes

PR #92933: fix(router): gracefully handle stale router state header during rolling deployments

Description (problem / solution / changelog)

Summary

When a client running Next.js 16.1.x connects to a 16.2.x server after a rolling deployment, the next-router-state-tree header is encoded in the old format. The current code throws a 500 error (The router state header was sent but could not be parsed) instead of falling back gracefully.

Root cause

The header format/encoding changed between 16.1 and 16.2. When the server (running 16.2) receives a header encoded by a 16.1 client, parseAndValidateFlightRouterState fails to parse it and throws instead of falling back to a full navigation.

Fix

In the catch block of parseAndValidateFlightRouterState, return undefined instead of throwing. Returning undefined signals to the caller that no valid router state is available, which triggers a full navigation — exactly the same behavior as when the header is absent.

The overload signature is updated from FlightRouterState to FlightRouterState | undefined to reflect that parse failure is now a non-fatal condition.

Fixes #92907

Changed files

  • packages/next/src/server/app-render/parse-and-validate-flight-router-state.tsx (modified, +7/-2)

Code Example

git clone https://github.com/abdonrd/nextjs-header-could-not-be-parsed
   cd nextjs-header-could-not-be-parsed
   npm install
   npm run build && npm start

---

npm install next@canary
   npm run build && npm start

---

Error: The router state header was sent but could not be parsed.
    at ignore-listed frames

---

Error: The router state header was sent but could not be parsed

---

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.3.0: Wed Jan 28 20:54:46 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T6000
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 24.14.1
  npm: 11.7.0
  Yarn: 1.22.19
  pnpm: 10.33.0
Relevant Packages:
  next: 16.2.1-canary.45
  eslint-config-next: N/A
  react: 19.2.5
  react-dom: 19.2.5
  typescript: 5.9.3
Next.js Config:
  output: N/A
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://github.com/abdonrd/nextjs-header-could-not-be-parsed

To Reproduce

  1. Clone the reproduction repository and install dependencies with Next.js 16.1.x (already pinned in package.json):
    git clone https://github.com/abdonrd/nextjs-header-could-not-be-parsed
    cd nextjs-header-could-not-be-parsed
    npm install
    npm run build && npm start
  2. Open http://localhost:3000 in a browser and keep it open.
  3. Upgrade Next.js to 16.2.x, rebuild, and restart the server (simulating a new deployment):
    npm install next@canary
    npm run build && npm start
  4. Without refreshing the browser, click the About link in the navigation.

The 500 Internal Server Error is thrown and navigation fails:

⨯ Error: The router state header was sent but could not be parsed.
    at ignore-listed frames

Current vs. Expected behavior

Current: Clicking a <Link> after a new deployment (upgrading from 16.1 to 16.2) throws an unhandled error in the console and navigation fails:

Error: The router state header was sent but could not be parsed

The error only reproduces when at least one layout or page is dynamically rendered. In this repo the root layout calls cookies(), which opts it into dynamic rendering. Removing that call (making the layout static) prevents the error.

Expected: Soft navigation works normally after a deployment.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.3.0: Wed Jan 28 20:54:46 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T6000
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 24.14.1
  npm: 11.7.0
  Yarn: 1.22.19
  pnpm: 10.33.0
Relevant Packages:
  next: 16.2.1-canary.45
  eslint-config-next: N/A
  react: 19.2.5
  react-dom: 19.2.5
  typescript: 5.9.3
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Cookies, Headers, Linking and Navigating

Which stage(s) are affected? (Select all that apply)

next start (local), Other (Deployed)

Additional context

https://github.com/user-attachments/assets/a2b67b7c-862b-4d09-b67e-5fe6602e411d

The format or encoding of this header appears to have changed between 16.1 and 16.2. When the server (running 16.2) receives a header encoded by the 16.1 client, it fails to parse it and throws instead of falling back to a full navigation.

The issue is latent until a new deployment is made, because that is when the server version changes while clients still carry stale 16.1 router state. Dynamic routes/layouts are more likely to trigger this path because they always go to the server for RSC payloads, whereas fully static pages may be served from cache without header validation.

extent analysis

TL;DR

Downgrade Next.js to version 16.1.x or wait for a fixed version to mitigate the router state header parsing error.

Guidance

  • Verify that the issue is resolved by downgrading Next.js to version 16.1.x and checking if navigation works as expected after a deployment.
  • Consider using a version pinning strategy to ensure consistent Next.js versions across deployments and avoid similar issues in the future.
  • If downgrading is not feasible, monitor the Next.js repository for a fix or update that addresses the changed header format or encoding between versions 16.1 and 16.2.
  • Test dynamic routes and layouts extensively to ensure they work correctly after any version changes or updates.

Notes

The provided information suggests that the issue is specific to the change in Next.js version from 16.1 to 16.2, and downgrading or waiting for a fix may be the most straightforward solutions.

Recommendation

Apply workaround: Downgrade Next.js to version 16.1.x, as this is the most straightforward way to mitigate the issue until a fixed version is available.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING