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 ==="
vercel inspect "$DEPLOY_URL" > "$BUNDLE_DIR/inspect.txt" 2>&1 || true
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
vercel logs "$DEPLOY_URL" --output=short --limit=100 \
> "$BUNDLE_DIR/function-logs.txt" 2>&1 || true
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
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
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)
vercel env ls > "$BUNDLE_DIR/env-vars-list.txt" 2>&1 || true
if [ -f "vercel.json" ]; then
cp vercel.json "$BUNDLE_DIR/vercel.json"
fi
if [ -f "package.json" ]; then
jq '{name, version, dependencies, devDependencies, engines}' package.json \
> "$BUNDLE_DIR/package-summary.json" 2>/dev/null || true
fi
{
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
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
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
| File | Contents |
|---|
inspect.txt | Deployment inspection output |
deployment.json | Deployment state, target, errors |
function-logs.txt | Recent function invocation logs |
events.json | Deployment event timeline |
build-info.json | Build configuration and output |
routes-functions.json | Route and function mapping |
env-vars-list.txt | Environment variable names (no values) |
vercel.json | Project configuration |
package-summary.json | Dependencies and versions |
environment.txt | System info (Node, CLI, OS) |
platform-status.json | Vercel platform status at time of capture |
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
| Error | Cause | Solution |
|---|
vercel inspect fails | Deployment deleted or token expired | Use API directly with curl |
jq: command not found | jq not installed | apt install jq or brew install jq |
| Empty function logs | Function not invoked or log retention expired | Check Observability tab in dashboard |
| VERCEL_TOKEN not set | Not authenticated for API calls | Export token or run vercel login |
Resources
Next Steps
For rate limit issues, see vercel-rate-limits.
