Users cannot navigate to URLs on older deployments after a new build is released

[ozgurozalp]

Summary

When they click on links, the page doesn’t load and gets stuck

We don't want to refresh page

• We do not want to force users to refresh the page with a warning.
• Old assets (all of them actually) are stored on Cloudflare R2 with their build IDs
• All assets remain always accessible, even after new builds are released.

Additional information

No response

Example

No response

[Denoroy737]

Hey @ozgurozalp 👋

I’ve faced this issue too when dealing with Next.js client navigation after new deployments.

What’s happening here is that when a user is still on an older deployment, their browser is using the previous build’s JavaScript bundle (which references that build’s routes and chunk files). Then, when they click a link, the Next.js router tries to prefetch or load chunks from the new build — but since the current HTML was generated from the old build, the router gets confused and hangs.

Even though you’ve stored all build assets in Cloudflare R2 (which is great), the browser is still trying to fetch assets with the new build ID, not the one it originally loaded with.

---

✅ The Root Cause

Next.js uses a build ID to ensure consistency between server and client bundles. When a new deployment happens:

• Your SSR (or serverless) responds with HTML from the new build ID
• But users on old sessions are still running old JS bundles
  → This mismatch causes the app to get stuck when navigating via next/link.

---

🧩 The Fix

1. Serve old HTML with its matching build ID

Since you already keep all build assets in R2, the key is to also serve the HTML (or app shell) that matches that specific build ID.
This means your routing logic (e.g., in Cloudflare Worker or your CDN layer) should detect the build version the client is using — and continue serving that version’s HTML and bundles together.

Basically:

Old session → old HTML + old chunks
New session → new HTML + new chunks

That way, even old sessions can navigate freely without breaking.

---

2. Avoid serving mixed builds

Make sure your CDN or edge function doesn’t serve new HTML that references new bundles to a user still using an old app shell.
If you’re using Cloudflare, you can version your _next and HTML responses by build ID — e.g.:

/_next/static/<buildId>/*
/docs/<buildId>/index.html

Then have the client stay within its build scope until it reloads.

---

3. (Optional) Smoothly upgrade users

If you want users to eventually move to the new version, you can add a lightweight version check — for example:

setInterval(async () => {
  const res = await fetch('/api/version')
  const latest = await res.text()
  if (latest !== window.__NEXT_DATA__.buildId) {
    // optionally show "New version available" toast
  }
}, 60000)

This way, you’re not forcing a refresh but can gently prompt users.

---

💡 TL;DR

• The app breaks because of build ID mismatch between client & server.
• Keep serving HTML + chunks from the same build for old sessions.
• Use your Cloudflare setup to version routes by build ID.
• Optionally notify users when a new build is live.

Once HTML and JS versions are aligned per build, navigation on old deployments will work perfectly without forcing refreshes.

[Denoroy737]

Hope this Helps!

[ozgurozalp]

Thanks for your help.
I’ve understood the general idea, but I still have a few questions.
Most of our pages are dynamic rather than static can we still apply this approach?
I’m having trouble figuring out exactly how to implement it.

[lewiii254]

You can still apply this approach even if most of your pages are dynamic.
The important part isn’t whether the page is static or dynamic — it’s that the HTML response and the JS chunks come from the same build ID.

With dynamic routes, the key is:

Always render the dynamic page using the same build version as the client

As long as you version your SSR entry point by build ID (just like your static assets), you can serve:

/_next/data/<buildId>/...dynamic-route.json
/_next/static/<buildId>/*
/html/<buildId>/dynamic-route

Your Cloudflare Worker (or whatever layer sits in front) just needs to:

1. Read the build ID from the client
   The client already knows its build ID from __NEXT_DATA__.buildId.

2. Serve dynamic routes from the matching build
   Instead of rendering with the latest build, route the request to:
   /html/<clientBuildId>/route
   or trigger the SSR function for that specific build.

This keeps navigation consistent because:

old client → old HTML → old chunks  
new client → new HTML → new chunks

So yes — even dynamic pages can be versioned

The dynamic logic (database queries, auth, etc.) stays the same. You’re only making sure the React runtime + RSC structure that wraps the dynamic data comes from the correct version.

[ozgurozalp]

I get the overall idea, but could you share a document or a source? I’m not sure how to implement it right now.