Diagnosing and fixing cache issues

Use this guide to diagnose and fix cache-related issues. You'll identify whether the problem is with the CDN cache, data cache, or build cache, and apply the right fix for each.

Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.

# 1. Check current response headers for cache status
vercel httpstat /path-with-stale-content
 
# 2. Search logs for cache-related issues
vercel logs --environment production --query "cache" --since 1h --expand
 
# 3. Identify the current deployment
vercel inspect <deployment-url>
 
# IF stale CDN content (HTML, assets, images):
vercel cache purge --type cdn --yes
vercel httpstat /path-with-stale-content    # verify content is fresh
 
# IF stale data cache (API responses, database queries):
vercel cache invalidate --tag my-cache-tag
# OR hard-delete if invalidation isn't enough:
vercel cache dangerously-delete --tag my-cache-tag --yes
 
# IF stale build cache (wrong build output):
vercel deploy --force --prod
 
# IF stale optimized images:
vercel cache invalidate --srcimg /images/hero.png

Start by checking the current cache status for the affected route. vercel httpstat shows response timing and lets you verify whether responses are served from cache:

vercel httpstat /path-with-stale-content

Run this two or three times in a row. If responses are consistently fast with similar timing, they're likely being served from the CDN cache.

Check production logs for cache-related entries that might explain the stale content:

vercel logs --environment production --query "cache" --since 1h --expand

Look for patterns like revalidation failures, cache key mismatches, or errors in your caching logic.

Check which deployment is currently serving production traffic:

vercel inspect <deployment-url>

Compare the deployment's Git commit with your latest code. If the deployment is older than expected, the issue might be that a recent deployment failed and an older cached version is serving traffic.

If the issue is stale HTML pages, static assets, or images being served from the CDN despite having new content deployed, purge the CDN cache:

vercel cache purge --type cdn --yes

After purging, verify the content is fresh:

vercel httpstat /path-with-stale-content

The first request after purging may be slower because it needs to regenerate the cache. Subsequent requests will be fast again.

If you're using the data cache (via fetch with next.revalidate or similar caching APIs) and the cached data is stale, invalidate it by tag:

vercel cache invalidate --tag my-cache-tag

You can invalidate multiple tags at once by separating them with commas:

vercel cache invalidate --tag products,pricing

If invalidation isn't clearing the stale data, hard-delete the cached entries:

vercel cache dangerously-delete --tag my-cache-tag --yes

If the deployed output seems wrong despite the latest code being committed, the build cache might contain stale artifacts. Force a fresh build without using the build cache:

vercel deploy --force --prod

If you want to skip the deployment cache but keep the build cache:

vercel deploy --force --with-cache --prod

If an optimized image is still showing an old version after you've replaced the source file, invalidate the image optimization cache:

vercel cache invalidate --srcimg /images/hero.png

Or hard-delete it:

vercel cache dangerously-delete --srcimg /images/hero.png --yes

• vercel cache
• vercel httpstat
• vercel inspect
• vercel logs
• CDN cache overview
• Debugging production 500 errors