vercel-advanced-troubleshooting

name	vercel-advanced-troubleshooting
description	Advanced debugging for hard-to-diagnose Vercel issues including cold starts, edge errors, and function tracing. Use when standard troubleshooting fails, investigating intermittent failures, or preparing evidence for Vercel support escalation. Trigger with phrases like "vercel hard bug", "vercel mystery error", "vercel intermittent failure", "difficult vercel issue", "vercel deep debug".
allowed-tools	Read, Grep, Bash(vercel:*), Bash(curl:*), Bash(jq:*)
version	1.18.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","vercel","debugging","advanced","troubleshooting"]
compatibility	Designed for Claude Code

Vercel Advanced Troubleshooting

Overview

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

Step 2: Cold Start Investigation

// Instrument cold start timing in your function
let coldStart = true;
const initTime = Date.now();

export default function handler(req, res) {
  const isCold = coldStart;
  coldStart = false;

  const handlerStart = Date.now();
  // ... your logic ...

  res.setHeader('x-cold-start', String(isCold));
  res.setHeader(, (handlerStart - initTime));
  res.({
    : isCold,
    : isCold ? handlerStart - initTime : ,
    : .() - handlerStart,
    : process..,
  });
}