Runtime logs now show cache reasons

Runtime logs now show cache reasons - Vercel

Runtime logs now show a Cache Reason explaining why a request wasn't a fresh cache hit, for example a time-based or tag-based revalidation. Use cache reasons to debug misses and improve your hit rate.

Cache reasons appear for any response the CDN can cache, including ISR, Partial Prerendering, and functions that set a Cache-Control header with directives like stale-while-revalidate . Responses rendered dynamically on every request don't have a cache reason.

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

Open the Logs tab and select a request to see the reason alongside its cache status. Each status and reason links to its entry in the Cache Status and Reasons reference.

A STALE request with a Time-based revalidation reason in runtime logs.

Copy link to heading From the CLI

Cache reason is available in vercel logs , vercel metrics , and Vercel plugin's cdn-caching skill :

1
# Inspect the cache reason for a request with vercel logs:
2
vercel logs
\
3
--request-id
<
request-id
>
\
4
--expand
--json
\
5
--project
<
project
>
\
6
--scope
<
team
>
7
8
# Quantify how often each reason occurs across your traffic with vercel metrics:
9
vercel metrics vercel.request.count
\
10
--group-by cache_reason
\
11
--since
<
time
>
\
12
--project
<
project
>
\
13
--scope
<
team
>
14
15
# Debug caching at scale using the cdn-caching skill in the Vercel plugin:
16
npx skills
add
https://github.com/vercel/vercel-plugin
--skill
cdn-caching

Learn more about cache statuses and reasons .