[v16.2+] Router state header was sent but could not be parsed on soft navigation with dynamic rendering
Nobody has claimed this yet.
- 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
- 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 - Open http://localhost:3000 in a browser and keep it open.
- 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 - 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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