Step-by-step guide

Persist the Next.js ISR Cache When Self-Hosting

Keep Next.js ISR consistent on persistent servers, containers, and multi-instance deployments with deliberate cache storage and invalidation.

By HostNextJS Editorial TeamReviewed by HostNextJS Technical Review Published Updated
01Typeguide
02Last reviewed
03Update policyReview every 90 days and after Next.js cache-handler changes.
At a glance

Deployment sequence

  1. STEP 01

    Identify the topology

    Determine whether the runtime is one persistent instance, an ephemeral container, or multiple instances.

  2. STEP 02

    Choose cache storage

    Keep local persistent disk for one instance or implement a supported durable shared handler for many.

  3. STEP 03

    Coordinate invalidation

    Ensure path and tag revalidation reaches every instance and survives restarts.

  4. STEP 04

    Test production behavior

    Observe HIT, STALE, MISS, and REVALIDATED behavior through deploys and failures.

On one next start instance with persistent local disk, the default Next.js cache persists naturally. Ephemeral containers lose local cache on replacement. Multiple instances each have separate caches unless you configure shared storage and coordinated invalidation.

Match storage to topology

For a single server, preserve the relevant .next cache path across application restarts while replacing immutable build assets by release. In containers, mount only the runtime cache path if persistence is desired; never share an entire mutable build directory across different releases.

For multiple instances, configure a production cache handler backed by durable shared storage and disable conflicting local memory behavior where required by the current API.

Coordinate tags and builds

All instances must run the same build. Multi-instance deployments also need consistent Server Function encryption, a deployment identifier for version-skew protection, shared cache behavior, and tag synchronization. A revalidateTag call received by one instance must not leave peers serving stale content.

Prove revalidation

Run production mode and inspect x-nextjs-cache values. Test time-based and on-demand revalidation, restart the process, replace a container, deploy a new build, and remove the cache backend temporarily. Define whether failure serves stale content, bypasses cache, or fails closed.

Methodology

How this resource was produced

The guide separates single persistent disk, ephemeral container, and multi-instance cache topologies because each has different consistency requirements.

Limitations
  • 01

    A shared data store alone is insufficient unless tag invalidation and failure behavior are coordinated.

  • 02

    Custom cache handlers require production-grade durability, eviction, errors, and observability.

Evidence

Sources and review record

Primary documentation checked for the material claims on this page. Product behavior and prices can change after the checked date.

  1. 01 · Next.jsHow to self-host Next.jsChecked July 12, 2026
  2. 02 · Next.jsIncremental Static RegenerationChecked July 12, 2026
Next step

Turn the resource into a deployment decision.

Review your cache topology