vercel-debug-bundle

What this skill does

# 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

```bash
#!/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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

| 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

- [Vercel Support Portal](https://vercel.com/support)
- [Vercel Logs CLI](https://vercel.com/docs/cli/logs)
- [Vercel Inspect CLI](https://vercel.com/docs/cli/inspect)
- [Vercel Status Page](https://www.vercel-status.com)

## Next Steps

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