Execute apply Vercel advanced debugging techniques for hard-to-diagnose issues.
Use when standard troubleshooting fails, investigating complex race conditions,
or preparing evidence bundles for Vercel support escalation.
Trigger with phrases like "vercel hard bug", "vercel mystery error",
"vercel impossible to debug", "difficult vercel issue", "vercel deep debug".
Diagnose hard-to-find Vercel issues: intermittent cold start failures, edge function crashes, region-specific behavior, function bundling problems, and serverless concurrency issues. Uses systematic isolation, request tracing, and Vercel-specific debugging techniques.
Prerequisites
Vercel CLI with access to production logs
Familiarity with vercel-common-errors (standard debugging)
curl and jq for API inspection
Access to deployment inspection tools
Instructions
Step 1: Request-Level Tracing
# Trace a single request through Vercel's edge network
curl -v https://yourdomain.com/api/endpoint 2>&1 | grep -E "x-vercel|cf-ray|age|cache"
# Key headers to check:
# x-vercel-id: <region>::<function-id> — which region served the request
# x-vercel-cache: HIT/MISS/STALE — edge cache status
# x-vercel-execution-region: iad1 — function execution region
# age: 45 — seconds since edge cached the response
# x-matched-path: /api/endpoint — routing match result
# Measure cold start frequency over N requests
for i in $(seq 1 20); do
curl -s https://yourdomain.com/api/endpoint \
| jq '{coldStart, initDuration, region}'
sleep 2 # Wait between requests to allow isolate recycling
done
Step 3: Function Bundle Analysis
# Check what's being bundled into your function
vercel inspect https://my-app-xxx.vercel.app
# Check function sizes in the deployment
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
"https://api.vercel.com/v13/deployments/dpl_xxx" \
| jq '.functions | to_entries[] | {path: .key, size: .value.size, regions: .value.regions}'
# Locally — check what @vercel/nft traces for a function
npx @vercel/nft print api/heavy-endpoint.ts 2>/dev/null | head -50
# Shows all files that will be bundled
# Find unexpectedly large dependencies
npx @vercel/nft print api/heavy-endpoint.ts 2>/dev/null \
| xargs -I {} du -sh {} 2>/dev/null | sort -rh | head -20
Step 4: Region-Specific Debugging
# Test from different regions to isolate geographic issues
# Use Vercel's deployment URL with region hints
for region in iad1 sfo1 cdg1 hnd1; do
echo "=== Region: $region ==="
curl -s -w "HTTP %{http_code} | Time: %{time_total}s\n" \
-H "x-vercel-ip-country: US" \
https://yourdomain.com/api/endpoint
done
# Check if the issue is region-dependent
# If latency varies wildly, check:
# 1. Function region vs database region (cross-region latency)
# 2. Edge middleware adding delay
# 3. External API calls from wrong region
Step 5: Edge Function Crash Debugging
// Edge functions crash silently on Node.js API usage
// Common crashes and their symptoms:
// Symptom: EDGE_FUNCTION_INVOCATION_FAILED with no error details
// Cause: Using Node.js Buffer, fs, crypto.createHash in edge runtime
// Diagnostic: check if imports are edge-compatible
export const config = { runtime: 'edge' };
export default function handler(request: Request) {
// This will crash silently:
// const hash = require('crypto').createHash('sha256');
// Use Web Crypto instead:
const encoder = new TextEncoder();
const data = encoder.encode('test');
const hashBuffer = await crypto.subtle.digest('SHA-256', data);
return Response.json({ ok: true });
}
# Check if a module is edge-compatible
npx edge-runtime --eval "import('your-module')" 2>&1
# Errors here mean the module won't work in edge functions
Step 6: Concurrency and Throttling Debug
# Check current function concurrency limits
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
"https://api.vercel.com/v9/projects/my-app" \
| jq '{plan: .plan, concurrency: .concurrencyBucketName}'
# Hobby: 10 concurrent, Pro: 1000, Enterprise: 100000
# Load test to find throttling threshold
npx autocannon -c 50 -d 10 https://yourdomain.com/api/endpoint
# Watch for 429 responses indicating FUNCTION_THROTTLED
Step 7: Systematic Isolation
Issue persists? Isolate systematically:
1. Does it happen on preview deployments?
└── No → Production-only env var or domain issue
2. Does it happen with a minimal function?
└── No → Issue is in your code, not Vercel platform
3. Does it happen in all regions?
└── No → Region-specific infrastructure issue
4. Does it happen with edge runtime?
└── No → Node.js-specific issue (cold starts, module compat)
5. Does it happen without middleware?
└── No → Middleware is interfering — check matcher scope
6. Create minimal reproduction:
└── api/test.ts with only the failing behavior
└── Deploy standalone and test
Step 8: Vercel Support Escalation
# Collect comprehensive evidence
mkdir vercel-debug && cd vercel-debug
# Deployment details
vercel inspect https://yourdomain.com > inspect.txt
vercel logs https://yourdomain.com --limit=200 > logs.txt
# Request trace
curl -v https://yourdomain.com/api/failing-endpoint 2>&1 > curl-trace.txt
# Function analysis
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
"https://api.vercel.com/v13/deployments/dpl_xxx" > deployment.json
# Platform status at time of issue
curl -s "https://www.vercel-status.com/api/v2/summary.json" > status.json
tar czf vercel-debug-$(date +%Y%m%d).tar.gz .
Output
Request traced through Vercel's edge network with region and cache data
Cold start frequency and duration quantified
Function bundle analyzed for size issues
Issue isolated to specific layer (edge, runtime, region, middleware)
