Vercel Debug Bundle

Vercel Debug Bundle

Overview

Collect a comprehensive debug bundle containing deployment state, function logs, environment configuration, and build output for Vercel support escalation or team troubleshooting.

Current State

!vercel --version 2>/dev/null || echo 'Vercel CLI not installed' !node --version 2>/dev/null || echo 'Node.js N/A'

Prerequisites

• Vercel CLI installed and authenticated
• Access to the affected deployment
• jq for JSON processing (recommended)

Instructions

Step 1: Collect Deployment Information

#!/usr/bin/env bash
set -euo pipefail

DEPLOY_URL="${1:-$(vercel ls --json 2>/dev/null | jq -r '.[0].url')}"
BUNDLE_DIR="vercel-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Collecting debug bundle for: $DEPLOY_URL ==="

# Deployment inspection
vercel inspect "$DEPLOY_URL" > "$BUNDLE_DIR/inspect.txt" 2>&1 || true

# Deployment details via API
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
  | jq '{uid, name, state, target, readyState, errorMessage, meta, regions}' \
  > "$BUNDLE_DIR/deployment.json" 2>/dev/null || true

Step 2: Collect Function Logs

# Recent function logs (last 100 entries)
vercel logs "$DEPLOY_URL" --output=short --limit=100 \
  > "$BUNDLE_DIR/function-logs.txt" 2>&1 || true

# Function logs via API with filtering
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v2/deployments/$DEPLOY_URL/events?limit=100&direction=backward" \
  | jq '.[] | {timestamp: .created, type, text}' \
  > "$BUNDLE_DIR/events.json" 2>/dev/null || true

Step 3: Collect Build Output

# Build logs
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
  | jq '.build' > "$BUNDLE_DIR/build-info.json" 2>/dev/null || true

# List all functions in the deployment
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
  | jq '.routes, .functions' > "$BUNDLE_DIR/routes-functions.json" 2>/dev/null || true

Step 4: Collect Environment State (Redacted)

# Environment variable names only (no values)
vercel env ls > "$BUNDLE_DIR/env-vars-list.txt" 2>&1 || true

# Project configuration (redacted)
if [ -f "vercel.json" ]; then
  cp vercel.json "$BUNDLE_DIR/vercel.json"
fi

# Package versions
if [ -f "package.json" ]; then
  jq '{name, version, dependencies, devDependencies, engines}' package.json \
    > "$BUNDLE_DIR/package-summary.json" 2>/dev/null || true
fi

# Node.js and CLI versions
{
  echo "node: $(node --version 2>/dev/null || echo 'N/A')"
  echo "npm: $(npm --version 2>/dev/null || echo 'N/A')"
  echo "vercel: $(vercel --version 2>/dev/null || echo 'N/A')"
  echo "os: $(uname -a)"
  echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
} > "$BUNDLE_DIR/environment.txt"

Step 5: Check Vercel Status Page

# Vercel platform status
curl -s "https://www.vercel-status.com/api/v2/summary.json" \
  | jq '{status: .status.description, components: [.components[] | {name, status}]}' \
  > "$BUNDLE_DIR/platform-status.json" 2>/dev/null || true

Step 6: Package the Bundle

# Create archive — excludes secrets
tar czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
echo "Debug bundle created: ${BUNDLE_DIR}.tar.gz"
echo "Contents:"
ls -la "$BUNDLE_DIR"/

Bundle Contents Reference

Support Ticket Template

Subject: [Project: my-app] FUNCTION_INVOCATION_TIMEOUT on /api/endpoint

Environment:
- Plan: Pro
- Framework: Next.js 14
- Region: iad1
- Node.js: 18.x

Issue:
[Describe the error, when it started, and the user impact]

Steps to Reproduce:
1. Deploy commit abc123
2. Send POST to /api/endpoint with body > 1MB
3. Function times out after 60s

Expected: 200 response within 5s
Actual: 504 after 60s

Deployment URL: https://my-app-xxx.vercel.app
Debug bundle: [attached]

Output

• vercel-debug-YYYYMMDD-HHMMSS.tar.gz archive
• All secrets redacted (env var values never captured)
• Platform status snapshot included
• Ready to attach to Vercel support ticket

Error Handling

Examples

Prepare a support bundle that is safe to share

Copy the deployment ID, timestamps, status-page snapshot, and a redacted request trace into a new temporary directory. Before archiving, scan the bundle for tokens, cookies, email addresses, and raw request bodies; replace values with stable placeholders so support can correlate events without receiving secrets. Encrypt or use the approved support attachment channel, set an expiry for the local bundle, and confirm the original deployment is still retained for follow-up.

Resources

• Vercel Support Portal
• Vercel Logs CLI
• Vercel Inspect CLI
• Vercel Status Page

Next Steps

For rate limit issues, see vercel-rate-limits.