AI & Agent Dev Bug Sandbox logo
AI & Agent Dev Bug Sandbox
Back to Radar

[V16.2+] Router State Header Was Sent But Could Not Be Parsed On Soft Navigation With Dynamic Rendering

After upgrading from Next.js 16.1 to 16.2, clients holding stale router state from the previous deployment send a header that the newer server cannot parse, causing a 500 error and failed soft navigation on dynamic routes/pages.

highConfidence 78%Next.jsAffected V16.2.0Affected V16.2.1-Canary.45

Origin Analysis

The encoding/format of the Next-Router-State-Tree header changed between 16.1 and 16.2. The 16.2 server invokes parseAndValidateFlightRouterState without catching decode/parse errors from older header payloads, so a stale client header triggers an unhandled exception instead of falling back to full navigation.
1. Deploy a Next.js app with a dynamic root layout (e.g. calls cookies()) on 16.1.x. Open it in a browser. 2. Upgrade the same app to 16.2.x and redeploy without refreshing the browser. 3. Click a client-side Link. Server receives a router state header encoded by 16.1, fails to parse, and throws `The router state header was sent but could not be parsed`.

Fixing Code Block

Edge Case Audit

Returning undefined may disable incremental rendering optimizations for affected navigations until the client refreshes. In concurrent or multi-instance deployments, some instances may still run versions that throw, so deploy this change together with a version pin or rollout. Rollback: if this patch causes regressions, revert to the previous throwing version; no data migration is required because the header is stateless.

Ecosystem Topology