vercel / vercel/next.js

[v16.2+] Router state header was sent but could not be parsed on soft navigation with dynamic rendering

Open
#92,907 6 comments 31 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Cookies Headers linear: next Linking and Navigating
Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

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.

Contributor guide

Open the contributing guide

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.

Research direction

Use the linked nextjs-header-could-not-be-parsed reproduction and follow the root layout's cookies() call and the navigation to the About page. Run the documented 16.1.x and 16.2.x build/start steps, then inspect router-state header handling across the version boundary. Done means soft navigation succeeds after a deployment with stale client state and dynamic rendering.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nextjs, react
Domain
backend, frontend, web-dev
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.