App Router: Flight decode can execute incompatible modules before build mismatch recovery during rolling deploy

[wa3l]

Link to the code that reproduces this issue

https://github.com/wa3l/nextjs-version-skew-repro

To Reproduce

1. Clone the repro repo.
2. Install dependencies.
3. Run: ./scripts/reproduce.sh
4. Open http://localhost:3000 immediately.
5. In DevTools Console, enable Preserve log.
   
6. Wait for the deploy message (~10s).
7. Click Other Page.
   Observed in console (example):

• Uncaught TypeError: (0 , n.tripleCount) is not a function
• thrown at module evaluation in a client chunk
• in some runs/environments: ChunkLoadError

Current vs. Expected behavior

Current behavior (unpatched):
During rolling-deploy skew (Build A runtime in browser, Build B RSC/navigation response from server), the client can execute incompatible modules/chunks before mismatch recovery and hit fatal runtime errors (TypeError / ChunkLoadError).

Expected behavior:
Build mismatch should be detected before Flight decode/evaluation of incompatible modules, so the client can hard reload first and avoid fatal runtime breakage.

Provide environment information

Operating System: macOS (darwin 25.3.0)
Node.js: 20+
next: 16.1.5
react: 19.x
react-dom: 19.x

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

Module Resolution

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

Other (Deployed)

Additional context

This appears to be an ordering problem in fetch-server-response during rolling deploy skew.

What skew means in this report

• Browser has already booted with Build A JS runtime and module registry in memory.
• A client-side navigation request is routed to a server now running Build B.
• The RSC/Flight payload references Build B modules/chunks.

Why this fails today

In fetch-server-response, decode can start in createFetch via createFromNextFetch(...) before the build mismatch check (flightResponse.b) is evaluated later in fetchServerResponse.

So there is a window where Build B module references are being decoded/resolved/evaluated inside a Build A-initialized runtime. That can produce:

• missing or incompatible export shape (TypeError: ... is not a function)
• chunk failures (ChunkLoadError) depending on asset mapping and cache/CDN behavior
• other runtime binding/context mismatches

What this repro intentionally proves

The repro intentionally creates deterministic A->B skew and forces one incompatible module path:

• ./scripts/reproduce.sh (unpatched): demonstrates fatal runtime break in browser before safe recovery.
• ./scripts/reproduce-fixed.sh (patched demo): same scenario, but with an early header check that forces hard reload before decode executes incompatible modules.

This is why the patched demo logs:

• [version-skew-fix] Early build mismatch detected; forcing hard reload

and avoids the fatal tripleCount is not a function crash.

Proposed fix direction

Make build identity available before decode (e.g. x-build-id response header) and check it before creating/awaiting Flight decode for navigation responses.

If mismatch:

• skip decode path
• trigger hard navigation/reload immediately

[xXMrNidaXx]

Production Perspective: This is Critical for Enterprise Deployments

This is a fantastic repro of a problem we've seen in production at scale. Rolling deploys with version skew are inevitable in any serious deployment, and the current behavior creates a poor UX (and sometimes data loss) window.

Why This Matters

In high-traffic apps, you can have thousands of users mid-navigation when a deploy goes out:

• Build A → Build B typically takes 30-60s for full propagation
• Users with open tabs are guaranteed to hit this window
• Current behavior = random runtime errors instead of graceful recovery

Workarounds We've Used

1. Deployment coordination via cookie/header:

// middleware.ts
export function middleware(request: NextRequest) {
  const buildId = process.env.NEXT_BUILD_ID;
  const clientBuildId = request.cookies.get('__next_build_id')?.value;
  
  if (clientBuildId && clientBuildId !== buildId) {
    // Force full page load instead of client navigation
    return NextResponse.redirect(request.url, {
      headers: { 'x-middleware-rewrite': request.url }
    });
  }
  
  const response = NextResponse.next();
  response.cookies.set('__next_build_id', buildId, { httpOnly: true });
  return response;
}

2. Service worker interception (for PWAs):

// Intercept navigation requests, check build version header
self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    // Clone request, check x-next-build-id header on response
    // If mismatch, clients.claim() + postMessage to reload
  }
});

3. Blue-green with sticky sessions:

For critical apps, we've moved to blue-green deployments with session affinity so users finish their session on the same build. More infra complexity but zero version skew.

On the Proposed Fix

The early header check approach in the repro is the right direction. Detecting mismatch before Flight decode is the key insight.

One consideration: the hard reload should preserve scroll position and any client-side state if possible. A location.reload() loses everything. Might be worth:

1. Stashing critical state to sessionStorage before reload
2. Or using a soft refresh pattern that re-fetches the page RSC but preserves React state where possible

Happy to help test patches against production traffic patterns.

---

Corey Nida — RevolutionAI | Production AI & Web Infrastructure

[markedwards]

We are suffering from perhaps a variation of this where Build A in the client executes a server action from a newer Build B on the server, gets a redirect from the successful action execution, but never redirects and there is no error or sign of a problem. The user just gets stranded until they refresh the browser.