Next.js Cache Debugging on Vercel

Published

Jul 14, 2026

Updated

Jul 15, 2026

Reading time

12 min read

"The cache is stale" can mean an old deployment, a cached public HTTP response, a tagged Next.js fetch, an optimized image, or data that was never cached. The safe response is not to purge first. It is to identify the layer, preserve a harmless body marker, and choose a recovery that matches the evidence.

At the scale a managed edge-orchestration layer runs — many routes and regions, several caching mechanisms stacked in front of one origin — that discipline has to be repeatable, not improvised. This guide treats Next.js cache debugging as a fixed decision flow with evidence at every step, not a set of purge commands reached for under pressure.

Follow the Next.js cache debugging decision flow

Use one URL and one expected value. For this scenario, Acme Shop expects /api/public-catalog to contain catalogRevision: "2026-07-14T10:00Z". A cache status without that body check is only a clue.

Capture Vercel cache headers before changing anything

Request the same public URL twice. -D - prints response headers and the default output prints the body, producing one shareable transcript without a private credential.

curl -sS -D - https://acme-shop-preview.example/api/public-catalog
curl -sS -D - https://acme-shop-preview.example/api/public-catalog

HTTP/2 200
content-type: application/json
cache-control: public, max-age=0, must-revalidate
x-vercel-cache: HIT
x-vercel-id: cle1::iad1::abc123

{"catalogRevision":"2026-07-14T10:00Z","products":[{"slug":"solar-pack","name":"Solar Pack","priceCents":12900}]}

For a protected preview, vercel curl (CLI v48.8.0+) and vercel httpstat (v48.9.0+, plus a local httpstat install) avoid placing a bypass secret in the command. Both are beta, so keep ordinary curl as the portable capture.

vercel curl /api/public-catalog --deployment https://acme-shop-preview.example
vercel httpstat /api/public-catalog --deployment https://acme-shop-preview.example

Read the cache-control headers the function actually sent

curl -D - only shows what reaches the client. Vercel has three related cache-control headers, and one never leaves the edge:

// Route handler: three targeted directives, three different audiences.
return new Response(JSON.stringify(catalog), {
  headers: {
    "content-type": "application/json",
    "Cache-Control": "public, max-age=0",
    "CDN-Cache-Control": "public, s-maxage=60",
    "Vercel-CDN-Cache-Control": "public, s-maxage=3600, stale-while-revalidate=300",
  },
})

Vercel-CDN-Cache-Control controls only Vercel's own edge; it is never forwarded to the browser or another CDN. CDN-Cache-Control is returned to the browser and downstream CDNs. If a function omits CDN-Cache-Control, Vercel strips s-maxage and any background-refresh directive from the cache-control the browser sees, substituting public, max-age=0, must-revalidate — exactly the header in the transcript above. A missing s-maxage in a curl capture is expected, not proof the route is uncached; trust x-vercel-cache and the body over the browser-facing cache-control value.

Identify the stale layer behind cache HIT MISS states

x-vercel-cache reports the CDN response state. It can be MISS for a dynamic route even when a server-side data fetch was cached. A harmless body revision and application logs are the evidence for the data layer.

Every cache HIT MISS states pair also carries a reason, which Vercel surfaces next to the header in the request's runtime log "Cache" section, and which changes what to do next:

Inspect the active deployment and contract

Confirm the deployment serving traffic before changing a cache rule. Then inspect the exact public response and the fetch that supplies it.

vercel inspect https://acme-shop-production.example
vercel logs --environment production --query "public-catalog" --since 1h --expand

// Public data: intentional persistence, fallback freshness, known invalidation target.
await fetch("https://catalog.acme-shop.example/v1/products", {
  cache: "force-cache",
  next: { revalidate: 300, tags: ["acme-shop:catalog"] },
})

// Private data: never make this a shared response.
await fetch("https://accounts.acme-shop.example/v1/me", {
  cache: "no-store",
  headers: { Authorization: `Bearer ${accessToken}` },
})

The fetch pattern above is the Next.js data cache, and it keeps working in Next.js 16 as long as the project has not opted into cacheComponents. If Acme Shop later enables cacheComponents: true and moves the catalog function to "use cache: remote" with cacheTag/cacheLife, that data moves into Vercel's Runtime Cache instead — check the project's Runtime Cache observability panel (reads, writes, hit rate, revalidations by tag) alongside logs, since a webhook success no longer guarantees the tagged entry refreshed in that region.

Check for Set-Cookie, request Authorization, private, no-cache, no-store, Vary: *, redirects, unsupported status codes, and body differences — any of these explains why a public response is not cacheable, and none should be bypassed to improve a metric. A response only becomes eligible for Vercel's CDN cache when: the request is GET/HEAD with no Range or Authorization header; the status is 200, 404, 410, 301, 302, 307, or 308; the body is under 10MB (20MB streaming); and the response has no Set-Cookie, no Vary: *, and no private/no-cache/no-store directive. A response that fails any one of these is correctly uncached — a contract issue to fix in the route, not a cache layer to purge.

Use the narrowest recovery

1. Wrong deployment: restore the approved known-good deployment, then repeat the same body check.
2. Wrong source or Next.js tagged data: correct the source and invoke Acme Shop's authenticated, allowlisted revalidation endpoint for its known tag and paths.
3. Wrong public CDN response: fix the route's output or headers first. Once correct, invalidate only the response's CDN tag from a reviewed linked-project session.
4. Optimized image: invalidate the specific source image; do not purge catalog or account responses.

# Only after the public response is correct and the tag scope is reviewed.
vercel cache invalidate --tag acme-shop:catalog-response

# Multiple related tags in one call, comma-separated, no spaces.
vercel cache invalidate --tag acme-shop:catalog-response,acme-shop:catalog-listing

# Image optimization keys off the source image URL, not the page tag.
vercel cache invalidate --srcimg /images/products/solar-pack.png

# Use only when immediate service restoration requires the approved prior release.
vercel rollback https://acme-shop-known-good.example

vercel cache invalidate --tag marks that tag stale: the next request serves the stale body instantly and refreshes it in the background, at no latency cost to the visitor — the narrow, default choice. dangerously-delete and a project-wide vercel cache purge --type cdn --yes behave differently on purpose: they delete the entry (or the whole project), so the next matching request blocks on a foreground fetch, and simultaneous requests for the same deleted entry can stampede the origin. Reserve them for when a stale response is worse than a slow one, and scope with --tag or --srcimg rather than a project-wide purge.

Prove recovery and record it

Keep the incident record small but complete: URL, expected and observed revision, timestamps, region header, deployment, command scope, operator, and final validation. Attach the runtime log's "Cache" section line for the validating request rather than retyping the reason. Never record secrets or private bodies.

Troubleshooting

Related guides

• Model public and private cache boundaries
• Revalidate public Next.js data on Vercel

Authoritative references

• Vercel: diagnosing cache issues
• Vercel CDN Cache
• Vercel response headers
• Vercel cache status and reasons
• Vercel: purging the CDN cache
• Next.js revalidateTag