Skip to content

Topics

Jump to a topic.

Search questions

Find a question by title, tag, or summary.

What breaks when you run a Next.js app on several instances?

Questions in this chapter (5)
  • Draft
  • hard
  • Askedoften
  • Verified November 2026

Answer

next start assumes it is alone. Its state splits into two kinds.

Per-instance caches. All on Next.js 16.4.5, next build && next start:

  • ISR and on-demand revalidation. Each instance regenerates its own copy, and revalidatePath/revalidateTag mark entries stale only in the process that ran them (measured in the ISR question).
  • use cache keeps an in-memory LRU per process, and use cache: remote is the same LRU until cacheHandlers.remote is set (see that question).
  • The image optimizer. The same /_next/image URL was MISS then HIT on instance A, then MISS again on B: each wrote its own file in .next/cache/images.

Per-build identity. Instances built separately differ even from the same commit:

  • Server Action IDs and encryption key. A build generates an AES key (or reuses one cached in .next/cache/.rscinfo for 14 days) and salts action IDs with it. Two fresh checkouts got different keys and different IDs, so an action posted to the other instance got 409 and Failed to find Server Action "0090f7…". This request might be from an older or newer deployment.
  • Build ID. It differs per build, so a client navigation answered by the other build turned into a full page reload.

The fixes the self-hosting guide lists:

  • build once and run that output everywhere, or set the same NEXT_SERVER_ACTIONS_ENCRYPTION_KEY (base64, 16, 24 or 32 bytes) at every build;
  • set deploymentId per deployment, so assets carry ?dpl= and mismatches reload instead of mixing versions;
  • configure cacheHandler (ISR, route handlers, and images with images.customCacheHandler: true) and cacheHandlers (use cache) backed by a shared store with a tag index, and cacheMaxMemorySize: 0 so no instance keeps a private copy. These handlers weren't built here.

Example

Same source, two fresh checkouts built separately. A small Node proxy sends HTML
document GETs to A (port 3301) and every other request to B (3302). Chrome 156:
load /, click a button that increments state, then one of three controls.

                                  save()      inline action      <Link href="/other">
keys differ (default)             409         409                full reload, A's HTML
                                  "This page couldn’t load"
same NEXT_SERVER_ACTIONS_         ran on B    ran on B,          full reload, A's HTML
ENCRYPTION_KEY                                "from-closure"
same key, deploymentId v1 / v1    ran on B    ran on B           client nav: "other build-B"
same key, deploymentId v1 / v2    ran on B    ran on B           full reload, A's HTML

Action IDs: random keys  A 0090f717…  40ddbd45…   B 009e44c9…  4044d6be…
            shared key   A 007fc0b2…  4002a022…   B 007fc0b2…  4002a022…

save is a module-level action; the inline one closes over label = 'from-closure', which travels encrypted with the form. With a shared key, B decrypted it and logged INLINE RAN from-closure. Firefox 159 gave the same results.

Pitfalls

  • Building per environment or per instance and assuming same commit means same build. Action IDs differed; only a shared key made them match.
  • Sharing one deploymentId across different builds. It silences skew detection: the navigation rendered B's page inside A's document.
  • Changing client code during a rolling deploy without routing by deployment. A's HTML asked B for 3spfmrl3-b19k.js?dpl=v1 and got 404; the page never hydrated, so the forms fell back to native POSTs. Next.js doesn't route on ?dpl=; that's the proxy's or CDN's job.
  • An in-process cache handler (a Map). The guide warns it gives each instance its own cache again.

Follow-ups

Why did a rebuild in the same folder keep working?
The second build reused the key from .next/cache/.rscinfo (it expires after 14 days), so IDs matched. A CI runner without that cache generates a new key.
What does a shared handler need for revalidateTag?
Per the docs: a tag index in the shared store for cacheHandler, and for cacheHandlers a refreshTags() that syncs tag state before each request, so a call on one instance invalidates everywhere.
With deploymentId set, what is the build ID?
Constant: both builds wrote the same BUILD_ID, and skew detection moved to the x-nextjs-deployment-id response header.

Comments

Comments are GitHub Discussions: you sign in with GitHub to post or react.