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": "test@example.com"}')
  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 support@clay.com"

Error Handling

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

Output

Generate a timestamped, redacted diagnostic archive with collection status, environment, correlation IDs, sanitized configuration, review decision, and support-case reference. The archive must not contain live secrets, raw lead or CRM records, or provider credentials; regenerate rather than manually editing an archive if sensitive data is found.

Examples

For a failing enrichment callback, collect only the sanitized HTTP status, table structure, and application correlation ID, then inspect the archive locally before submitting it to support. If a log contains a contact email or secret, quarantine the archive, fix the collection filter, and create a new bundle instead of sending a partially redacted copy.

Resources

• Clay Community Support
• Clay University Docs

Next Steps

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