Vercel Runtime Logs Now Show Cache Reasons for Faster Cache Debugging

Vercel has added a Cache Reason field to its runtime logs, giving developers a direct explanation for why a request did not result in a fresh cache hit. The new field appears in the Logs tab, alongside existing cache status labels, and covers responses served by ISR (Incremental Static Regeneration), Partial Prerendering, and any function that sets a Cache-Control header. It is also accessible from the CLI via vercel logs, vercel metrics, and the Vercel plugin's cdn-caching skill.

What happened

Cache Status	Possible Reasons
MISS	Cold, Request collapsed, Error
BYPASS	Draft Mode, Prerender Bypass, Crawler
STALE	Time-based revalidation, Tag-based invalidation, Revalidation error
REVALIDATED	Tag-based deletion

Vercel’s runtime logs now include a Cache Reason field for each request that the CDN could have served from cache. The reason tells you specifically why the CDN did not return a fresh cached response, narrowing down a previously opaque status code into an actionable cause.

Cache reasons appear for responses generated by ISR (a Next.js pattern that rebuilds static pages in the background after a set interval), Partial Prerendering (a hybrid rendering mode that streams a static shell with dynamic slots), and any serverless function that returns a Cache-Control header with directives like stale-while-revalidate. Fully dynamic responses, those rendered fresh on every single request, do not carry a reason because there is nothing to cache in the first place.

How to read the new cache reasons

Open the Logs tab in your Vercel project dashboard and click any request. The Cache Reason appears next to the cache status. Both the status and the reason are clickable links pointing to Vercel’s Cache Status and Reasons reference documentation.

From the command line, the same data is available in three places:

• vercel logs: per-request log output
• vercel metrics: aggregated cache performance data
• Vercel plugin cdn-caching skill: integrated cache insights inside the plugin

Why does cache hit rate actually matter for your site?

Every request that misses the CDN cache travels all the way to an origin serverless function. That adds latency, burns compute, and increases your bill. A higher cache hit rate means faster page loads for end users and lower hosting costs for you. Until now, diagnosing a poor hit rate meant guessing from a status label alone. Knowing the specific reason, whether it was a cold start, a crawler bypassing cache, or a tag-based invalidation firing too often, points you directly at the fix.

For teams running e-commerce sites or content-heavy builds on Vercel, this kind of visibility is particularly useful. Aggressive tag-based invalidation, for example, can silently destroy cache efficiency after every CMS publish. A STALE + “Tag-based invalidation” reason in the logs is much clearer signal than a raw STALE status with no context.

Why it matters

Caching behaviour on modern hosting platforms has grown complex. ISR, PPR, edge middleware, and custom Cache-Control headers each interact with the CDN in different ways. Developers have historically had to instrument their own logging or rely on trial and error to figure out what was causing unexpected misses. A first-party reason field removes a whole category of that guesswork.

This also matters for teams using web development frameworks like Next.js on Vercel at scale, where even a small improvement in cache hit rate can meaningfully reduce serverless invocation costs.

Our take

This is a small but genuinely useful quality-of-life improvement. Cache debugging on Vercel has always required some archaeology: check the status, read the docs, form a hypothesis, redeploy. Adding the reason directly into the log entry cuts that loop short.

The thing to watch is whether the reason labels stay granular enough to be useful as Vercel adds more rendering modes. “Error” as a MISS reason, for instance, is still fairly broad. But for the most common scenarios, particularly time-based versus tag-based revalidation confusion, this should save real debugging time.

If you manage a Next.js or similar project on Vercel and cache hit rate is a concern, check our ongoing care plan for how we monitor and tune performance for client sites. For broader questions about caching strategy in your stack, the Lumien team is happy to take a look.

Practical takeaway: Next time your Vercel site feels slower than expected, open the Logs tab and filter for MISS and STALE reasons before changing any code.

Source: Vercel Blog