Vercel Cache Reason: Stop Treating MISS, BYPASS, and STALE as One Cache Problem
A cache status tells you what happened; Cache Reason explains why. Since July 17, 2026, Vercel runtime logs expose the reason when a cacheable response was not a fresh hit, letting teams split capacity, policy, and revalidation incidents.
Why status needs a reason
Reasons apply to CDN-cacheable responses such as ISR, Partial Prerendering, and functions with cache headers. A fully dynamic response can legitimately have no reason.
| Status | Typical reason | Operational meaning |
|---|---|---|
| MISS | Cold · Request collapsed · Error | Origin generated because no usable cache entry existed |
| BYPASS | Draft Mode · Prerender Bypass · Crawler | Cache intentionally skipped |
| STALE | Time-based · Tag invalidation · Revalidation error | Old response served while refreshing |
| REVALIDATED | Tag-based deletion | Foreground regeneration after deletion |
Operational checklist
✓Treat MISS + Cold as a prerendering, lifetime, or regional eviction question.
✓Do not count BYPASS + Draft Mode/Crawler as an automatic cache regression.
✓Investigate origin failures when STALE carries Revalidation error while users still receive the last good response.
✓Group vercel.request.count by cache_reason to move from one request to fleet-level evidence.
Bottom line
The goal is not one maximum HIT rate. Measure latency, origin load, freshness, and hidden revalidation failure per reason.