Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
If a Next.js page on Vercel still shows old content after you call a revalidation API, that does not by itself mean the call failed. Invalidation and fresh content delivery are separate events: depending on the router and API, the next request may trigger revalidation, stale output may be served while regeneration runs, or a regeneration error may leave the last successful page in cache. Find the cache model first, then trace the invalidation target, the request that should regenerate it, and the result.
First identify the route and cache model
“ISR” can refer to different mechanisms depending on whether the route uses the Pages Router or App Router, which Next.js version is deployed, and whether freshness is controlled by a time interval, path invalidation, or cache tags. A route that looks stale only in development may behave differently in a production build.
Before changing code, record:
- Whether the route uses the Pages Router or App Router, and the deployed Next.js version.
- Whether freshness is time-based or triggered by
revalidatePath,revalidateTag, or another API. - Whether you observed the behavior on the deployed URL or only in development.
- The exact URL requested, the invalidation endpoint and payload, and the response from that endpoint.
Next.js documents ISR behavior and version-specific mechanisms in its ISR guide. Avoid diagnosing a generic “ISR failure” before identifying which mechanism the route actually uses.
Check what the invalidation call promises
revalidatePath marks a path for revalidation
In an App Router Route Handler, revalidatePath marks the specified path. The next request to that path triggers revalidation; the call alone does not promise that a fresh page has already been generated. The API accepts a literal path or a route pattern. For a dynamic pattern, provide the appropriate page or layout type. Paths are case-sensitive. See the Next.js revalidatePath reference.
#1 Best Overall
revalidateTag targets tagged data
A tag can invalidate only data that was assigned that same tag when cached. Next.js documents tags on fetch through next.tags, and through cacheTag inside a 'use cache' function or component. Tag matching is case-sensitive.
With the documented revalidateTag(tag, 'max') behavior, revalidation is request-triggered: pages that use the tagged data revalidate as they are visited, not all at once when the call runs. The Next.js revalidateTag reference explains the API and its cache profile semantics.
Match the invalidation target to the cached entry
Account for route files and rewrites
For revalidatePath, use the path corresponding to the route file, not automatically the URL a visitor sees. If a rewrite maps /blog to /news, invalidate /news, the destination route. A mismatch in path or capitalization can leave the intended cache entry untouched.
Rank #2
Use the right scope for shared content
revalidatePath targets a route path, page, layout, or matching pattern. Tags target cached data and can be useful when the same content feeds multiple routes. If a content update appears on several pages, establish whether each page has its own route output or reads shared tagged data before choosing an invalidation API.
On-demand ISR requests do not execute Proxy, so Proxy-based rewrites or logic may not run during invalidation. Use the exact destination path rather than relying on Proxy to transform it. These path and tag distinctions are covered in the path API and tag API documentation.
Make the request that triggers regeneration
After a successful on-demand invalidation call, request the affected route. For Route Handler path revalidation and tag revalidation, the next visit is the relevant trigger; do not infer that a webhook response means the page was rebuilt eagerly.
Time-based ISR has a related behavior: after the revalidation interval has elapsed, the first request may receive the stale cached response while regeneration runs in the background. A later request can receive the newly generated page if that regeneration succeeds. The Next.js ISR guide describes this stale-while-revalidate flow.
Look for a regeneration error before blaming invalidation
When regeneration throws, Next.js keeps serving the last successfully generated version and retries on a later request. Persistent old output can therefore be evidence of a render or data-fetch failure, not proof that Vercel ignored an invalidation request.
Inspect server or function logs around the request that should regenerate the page. Check the data source, rendering path, and any code that can throw. Treat the invalidation endpoint’s response and the regeneration outcome as separate observations: success from one does not establish success of the other.
Use production-like conditions and cache evidence
Reproduce outside development
The Next.js guide recommends testing ISR with next build followed by next start. ISR requires the Node.js runtime and is not supported with static export. Confirm the deployed route is running in a compatible environment before treating the behavior as a cache defect.
Inspect cache status
For supported deployments, the guide documents NEXT_PRIVATE_DEBUG_CACHE=1 for logging ISR cache hits and misses. It also describes the x-nextjs-cache response header:
Free tools Windows power users keep installed
One-click scans. No signup required.
HIT: a cached response was served.STALE: stale content was served while background revalidation is occurring.MISS: the response was rendered fresh because it was absent from cache.REVALIDATED: regeneration occurred through on-demand revalidation.
Use the header and logs together with the exact request sequence. A single response may show what was served without explaining why regeneration failed; correlate it with the request that was expected to trigger regeneration.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Separate the cache layers and deployment assumptions
Identify which value is stale
A route can involve cached rendered output as well as cached data. The value that looks old might come from the route output, a cached fetch or other data, client-side state, or an upstream CMS or API. Determine which layer contains the old value before changing the invalidation mechanism. Next.js’s separate path and tag APIs, and Vercel’s discussion of more granular data caching, make it important not to treat “the Vercel cache” as one undifferentiated entry. See Vercel’s discussion of ISR and data caching.
Check whether multiple instances share cache state
For self-hosted multi-instance deployments, Next.js documents that the default filesystem cache is per instance. An invalidation received by one instance does not automatically invalidate another unless a shared cache handler coordinates them. This qualification concerns self-hosted deployments; do not assume it explains a Vercel deployment without evidence about the actual runtime and cache path.
Choose the API for the desired scope and freshness
The right API depends on whether you need to refresh a route or shared data, where the update is initiated, and whether stale-while-revalidate is acceptable.
| Approach | Targets | Useful when | Timing or context |
|---|---|---|---|
Time-based revalidate |
Route or data freshness on a configured interval | Content can tolerate bounded staleness | The first request after expiry may receive stale output while regeneration runs. Next.js ISR guide |
revalidatePath(path, type?) |
A route path, page, layout, or matching pattern | A content change maps to a route or route family | In a Route Handler, the next visit triggers revalidation; account for destination paths where rewrites exist. Next.js API reference |
revalidateTag(tag, 'max') |
Data assigned the matching cache tag, potentially shared across routes | A data change affects multiple pages | The tag must be attached and match; visiting a page using it triggers revalidation with stale-while-revalidate semantics. Next.js API reference |
updateTag(tag) |
Tagged data | A Server Action needs read-your-own-writes behavior | Vercel Academy describes this for Server Actions; it is not the Route Handler webhook option. Vercel Academy: updateTag |
Do not substitute one API for another solely because both are called “revalidation.” Compare the target, invocation context, and freshness behavior against the route’s requirements.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
