Common mistakes with Vercel ISR cache invalidation in Next.js 15

Implementation failures and path errors

Developers frequently define unstable_cache inside function bodies. This mistake creates a new cache instance every time the function runs. This defeats caching. Developers define unstable_cache at the module level. This ensures the application creates a single cache instance when the module loads.

Another common error involves using revalidatePath in Client Components. This function only works in server environments like Server Actions or Route Handlers. It cannot be called in a Proxy.

Use server environments.

The path parameter must match the route file structure exactly. Do not append /page or /layout to the path string. If the path contains a dynamic segment like /product/[slug], the type parameter is required. The path string cannot exceed 1024 characters. When developers use revalidatePath with rewrites, they must pass the destination path rather than the source path visible in the browser. Revalidating a layout invalidates that segment and all nested pages beneath it. Revalidation of a page only invalidates that specific page.

If a developer sets revalidate: 31536000 or Infinity, Vercel provides broken behavior. The server serves empty cached responses with incorrect content-type headers.

revalidateTag marks data as stale, while updateTag expires it. Revalidating a layout invalidates the segment and all nested components. Revalidation of a page only invalidates that specific page. If a developer uses fetch with no-store or an explicit revalidate: 0, the route renders dynamically and bypasses the cache.

The two caching layers

The Client Router Cache causes stale data even after revalidateTag succeeds. Next.js keeps an in-memory cache of RSC payloads in the browser. This cache defaults to a 300 second expiry for static pages. If a user sees stale content after a mutation, the browser is likely serving a cached payload. This can lead to a 15 minute delay before everything syncs.

You can mitigate this by configuring staleTimes in next.config.ts, assuming you are familiar with the configuration file structure. Developers set static to 30 seconds to reduce the hold on static page payloads. Alternatively, call router.refresh() on the client after a mutation. This forces the router cache to bypass the existing payload and request fresh data from the server. router.refresh() does not perform a full page reload. It re-requests the current route from the server and updates the router cache in place.

Does the client-side cache always require a manual refresh?

Check the x-vercel-cache header to see the status. Values include HIT, STALE, MISS, and REVALIDATED.

Infrastructure and environment conflicts

When developers use Cloudflare in front of Vercel, a cache rule that sets an explicit Edge TTL overrides Vercel’s instructions and prevents the background revalidation process from completing successfully. Vercel uses s-maxage and stale-while-revalidate to manage its background regeneration. If Cloudflare holds a stale copy past its own TTL, the revalidation callback never triggers.

Developers must enable the Verified Proxy setting in Vercel to avoid 403 errors. ISR is not supported on Cloudflare Pages. This platform uses the edge runtime, which is incompatible with the Node.js Prerender functions Vercel uses for ISR.

On Vercel, revalidation runs in a serverless function. This environment is separate from the initial build environment. The serverless function cannot access files in the filesystem that the original build wrote. This makes downloading images to the local filesystem during revalidation impossible.

In multi-instance deployments, the default filesystem cache is per-instance. On-demand revalidation only invalidates the instance that receives the call. Verify production behavior by running next build and next start locally to test ISR behavior.

A developer using VERCEL_FORCE_NO_BUILD_CACHE=1 can prevent outdated content during Git deploys. This setting opts out of the Vercel build cache.

It doubles build time.