Clay Advanced Troubleshooting

Overview

Deep debugging techniques for complex Clay issues that resist standard troubleshooting. Covers provider-level isolation, waterfall diagnosis, HTTP API column debugging, Claygent failure analysis, and Clay support escalation with proper evidence.

Prerequisites

• Access to Clay table with the failing enrichments
• curl and jq for API testing
• Understanding of Clay's enrichment architecture (providers, waterfall, columns)
• Browser developer tools for network inspection

Instructions

Step 1: Isolate the Failure Layer

#!/bin/bash
# clay-layer-test.sh — test each integration layer independently
set -euo pipefail

echo "=== Layer Isolation Test ==="

# Layer 1: Webhook delivery
echo "Layer 1: Webhook"
WEBHOOK_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST "$CLAY_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"_debug": true, "domain": "google.com"}')
echo "  Webhook: $WEBHOOK_CODE"

# Layer 2: Enterprise API (if applicable)
if [ -n "${CLAY_API_KEY:-}" ]; then
  echo "Layer 2: Enterprise API"
  API_RESULT=$(curl -s -X POST "https://api.clay.com/v1/companies/enrich" \
    -H "Authorization: Bearer $CLAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain": "google.com"}')
  echo "  API response keys: $(echo "$API_RESULT" | jq 'keys')"
fi

# Layer 3: HTTP API callback endpoint
echo "Layer 3: Callback endpoint"
CALLBACK_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST "${CLAY_CALLBACK_URL:-http://localhost:3000/api/clay/enriched}" \
  -H "Content-Type: application/json" \
  -d '{"_debug_test": true}')
echo "  Callback: $CALLBACK_CODE"

echo ""
echo "First failing layer = root cause location"

Step 2: Diagnose Enrichment Column Failures

In the Clay UI, click on red/error cells to see detailed error messages:

# Common enrichment column error patterns and root causes:
errors:
  "No data found":
    meaning: "Provider has no data for this input"
    check:
      - Is the input domain valid? (not personal email domain)
      - Is the input name spelled correctly?
      - Is the provider connected? (Settings > Connections)
    fix: "Add more waterfall providers for broader coverage"

  "Rate limit exceeded":
    meaning: "Provider API rate limit hit"
    check:
      - How many rows are processing simultaneously?
      - Is the provider's rate limit known? (see provider docs)
    fix: "Reduce table row count, add delay between batches"

  "Invalid API key":
    meaning: "Provider connection lost or key expired"
    check:
      - Go to Settings > Connections
      - Click on the failing provider
      - Test the connection
    fix: "Reconnect with a valid API key"

  "Timeout":
    meaning: "Provider took too long to respond"
    check:
      - Is the provider's status page showing issues?
      - Is the input data unusually complex?
    fix: "Retry the column on failed rows (click cell > retry)"

  "Column dependency not met":
    meaning: "A column this enrichment depends on hasn't completed yet"
    check:
      - Check column order (left to right execution)
      - Is the prerequisite column populated?
    fix: "Reorder columns so dependencies run first"