clay-debug-bundle

Clay Debug Bundle

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A'

Overview

Collect all diagnostic information needed for Clay support tickets. Clay is a web platform, so debugging focuses on webhook delivery, enrichment column errors, HTTP API responses, and credit consumption -- not pods or clusters.

Prerequisites

• Clay account with access to affected table
• curl for testing webhook/API connectivity
• Browser developer tools for capturing network requests

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# clay-debug-bundle.sh — collect Clay integration diagnostics
set -euo pipefail

BUNDLE_DIR="clay-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Clay Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 2: Test Webhook Connectivity

# Test webhook endpoint is reachable
echo "--- Webhook Test ---" >> "$BUNDLE_DIR/summary.txt"
WEBHOOK_URL="${CLAY_WEBHOOK_URL:-not_set}"
if [ "$WEBHOOK_URL" != "not_set" ]; then
  HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/webhook-response.txt" -w "%{http_code}" \
    -X POST "$WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d '{"_debug": true, "_test": "debug-bundle"}')
  echo "Webhook HTTP Status: $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"
  echo "Webhook URL: ${WEBHOOK_URL:0:50}..." >> "$BUNDLE_DIR/summary.txt"
else
  echo "CLAY_WEBHOOK_URL: NOT SET" >> "$BUNDLE_DIR/summary.txt"
fi

Step 3: Capture Environment and Configuration

# Capture environment (redacted)
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "Python: $(python3 --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -s -r)" >> "$BUNDLE_DIR/summary.txt"
echo "CLAY_API_KEY: ${CLAY_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "CLAY_WEBHOOK_URL: ${CLAY_WEBHOOK_URL:+[SET]}" >> "$BUNDLE_DIR/summary.txt"

# Capture .env (redacted)
if [ -f .env ]; then
  sed 's/=.*/=***REDACTED***/' .env > "$BUNDLE_DIR/config-redacted.txt"
fi

Step 4: Test Enterprise API (If Available)

echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Enterprise API Test ---" >> "$BUNDLE_DIR/summary.txt"
if [ -n "${CLAY_API_KEY:-}" ]; then
  API_CODE=$(curl -s -o "$BUNDLE_DIR/api-response.txt" -w "%{http_code}" \
    -X POST "https://api.clay.com/v1/people/enrich" \
    -H "Authorization: Bearer $CLAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"email": "[email protected]"}')
  echo "Enterprise API Status: $API_CODE" >> "$BUNDLE_DIR/summary.txt"
else
  echo "Enterprise API: No API key configured" >> "$BUNDLE_DIR/summary.txt"
fi

Step 5: Capture Application Logs

# Grab recent Clay-related log entries
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Recent Errors ---" >> "$BUNDLE_DIR/summary.txt"

# Search for Clay errors in common log locations
for logfile in logs/*.log /tmp/clay-*.log; do
  if [ -f "$logfile" ]; then
    grep -i "clay\|webhook\|enrich" "$logfile" 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"
  fi
done

# Check npm logs for module issues
if [ -d node_modules ]; then
  echo "Dependencies installed: YES" >> "$BUNDLE_DIR/summary.txt"
  ls package.json 2>/dev/null && echo "package.json: EXISTS" >> "$BUNDLE_DIR/summary.txt"
fi

Step 6: Collect Clay Table Info (Manual Steps)

Add to the debug bundle manually from the Clay UI:

## Clay Table Diagnostics (fill in from Clay UI)

- Table Name: _______________
- Table URL: _______________
- Row Count: _______________
- Enrichment Columns: _______________
- Auto-run enabled: YES / NO
- Error cells visible: YES (count: ___) / NO
- Credit balance remaining: _______________
- Plan tier: Free / Starter / Explorer / Pro / Enterprise

## Error Details (from clicking red cells)
- Error message: _______________
- Error column: _______________
- Error row count: _______________

## Recent Changes
- Last table edit: _______________
- Any new columns added: _______________
- Any provider connections changed: _______________

Step 7: Package and Review

tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo ""
echo "BEFORE SUBMITTING: Review for sensitive data!"
echo "  - Check $BUNDLE_DIR/config-redacted.txt for leaked secrets"
echo "  - Check $BUNDLE_DIR/logs.txt for PII (emails, names)"
echo ""
echo "Submit at: https://community.clay.com or [email protected]"

Error Handling

Item	Purpose	Included
Webhook connectivity	Verify data can reach Clay	Automated
Environment info	Compatibility check	Automated
Enterprise API test	Verify API key validity	Automated
Application logs	Error patterns	Automated
Table diagnostics	Clay-side configuration	Manual checklist
Config (redacted)	Secret management issues	Automated

Sensitive Data Handling

Always redact before submitting:

• API keys and tokens
• Email addresses and names from enrichment data
• Provider API keys (Apollo, Clearbit, etc.)
• CRM credentials

Safe to include:

• Error messages and HTTP status codes
• Column names and table structure
• Credit usage numbers
• Software versions

Resources

• Clay Community Support
• Clay University Docs

Next Steps

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