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

Stale Route-Cache Entries Survive In-Place Deploy Since Next.Js 16.3.8

After upgrading to Next.js 16.3.8, deployments that patch the existing .next directory in place (rather than recreating it) leave stale route-cache entries, causing 404s for CSS/JS assets. The root cause is that the route-cache key no longer includes a build identifier, so cached entries from the previous build remain valid after a new deploy.

highConfidence 85%Next.jsAffected V16.3.8Affected V16.4.0-Canary.60

Origin Analysis

The route-cache key in route-cache-key.ts was changed in PR #99482 to no longer depend on the build identifier. As a result, when .next/server/route-cache persists across an in-place deploy (because the deploy tool only uploads changed files and does not clear runtime files), the new build reuses stale cache entries that point to old asset URLs, causing 404s.
1. Clone https://github.com/mcdado/next-route-cache-stale-repro 2. Run npm install 3. Run ./repro.sh to simulate a non-atomic in-place deployment where .next/server/route-cache is preserved 4. Start the app with `next start` 5. Observe that CSS/JS assets return 404 after the deploy

Fixing Code Block

Edge Case Audit

This change invalidates all existing route-cache entries immediately after upgrade, which may cause a temporary increase in server load as caches are rebuilt. If a custom server does not set __NEXT_BUILD_ID, the key will degrade to a constant prefix (or empty string), potentially reintroducing the bug; ensure that all server entry points set this variable. During rolling/simultaneous deploys with multiple server instances, mixing old and new processes could cause inconsistent cache keys; use atomic deploy switches or clear the cache during the transition. Rollback requires reverting this change and manually deleting .next/server/route-cache to avoid stale data.

Ecosystem Topology