Vercel runtime logs now expose a Cache Reason field, showing exactly why a request failed to get a fresh cache hit. Reasons are grouped by status: MISS surfaces Cold, Request collapsed, or Error; BYPASS surfaces Draft Mode, Prerender Bypass, or Crawler; STALE surfaces Time-based revalidation, Tag-based invalidation, or Revalidation error; REVALIDATED surfaces Tag-based deletion.
Coverage spans any CDN-cacheable response: ISR, Partial Prerendering, and functions using Cache-Control directives like stale-while-revalidate. Purely dynamic responses, rendered on every request, produce no cache reason. Access is available in the Logs tab UI, vercel logs CLI, vercel metrics, and the Vercel plugin cdn-caching skill.
The reason why this is worth reading in full is the reference table mapping every status to its discrete reason set, which is the fastest path to diagnosing why your hit rate is lower than expected. Each status and reason in the UI links directly to the Cache Status and Reasons reference doc.
[READ ORIGINAL →]