clay-advanced-troubleshooting

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"

Step 3: Debug HTTP API Column Issues

// debug/http-api-column.ts — replicate Clay's HTTP API column call locally
async function debugHTTPAPIColumn(
  url: string,
  method: string,
  headers: Record<string, string>,
  body: Record<string, string>,
  sampleRow: Record<string, string>,
): Promise<void> {
  // Replace {{column_name}} placeholders with sample data
  let resolvedUrl = url;
  let resolvedBody = JSON.stringify(body);

  for (const [key, value] of Object.entries(sampleRow)) {
    const placeholder = `{{${key}}}`;
    resolvedUrl = resolvedUrl.replace(placeholder, value);
    resolvedBody = resolvedBody.replace(new RegExp(placeholder.replace(/[{}]/g, '\\$&'), 'g'), value);
  }

  console.log('Resolved URL:', resolvedUrl);
  console.log('Resolved body:', JSON.parse(resolvedBody));

  const res = await fetch(resolvedUrl, {
    method,
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: method !== 'GET' ? resolvedBody : undefined,
  });

  console.log('Status:', res.status);
  console.log('Response:', await res.text());
}

// Test with your actual column config and sample row data
await debugHTTPAPIColumn(
  'https://api.hubapi.com/crm/v3/objects/contacts',
  'POST',
  { 'Authorization': 'Bearer your-hubspot-key' },
  { email: '{{Work Email}}', firstname: '{{first_name}}' },
  { 'Work Email': 'test@example.com', 'first_name': 'Jane' },
);

Step 4: Debug Claygent Failures

Common Claygent issues and diagnosis:

claygent_debugging:
  empty_results:
    symptom: "Claygent returns empty or 'Could not find information'"
    diagnosis:
      - Test the prompt manually in Clay's Claygent builder (click cell > edit)
      - Try the URL in a browser — is the website accessible?
      - Check if the website blocks bots (CloudFlare challenge page)
    fixes:
      - Use Navigator mode for JavaScript-heavy sites
      - Simplify the prompt to a single question
      - Add fallback sources: "If not on the website, check LinkedIn/Crunchbase"

  inconsistent_results:
    symptom: "Same prompt returns different data each time"
    diagnosis:
      - Claygent uses web search which can vary
      - Dynamic website content changes between requests
    fixes:
      - Make prompts more specific (exact page URL vs general domain)
      - Add structured output format: "Return as JSON with keys: funding_amount, date, investors"

  high_credit_cost:
    symptom: "Claygent consuming too many credits"
    diagnosis:
      - Each Claygent call costs credits + 1 action
      - Running on all rows including low-value ones
    fixes:
      - Add conditional run: "Only run if ICP Score >= 60"
      - Cache results: don't re-run on already-researched companies

Step 5: Build a Support Escalation Package

## Clay Support Escalation

**Account:** [your email]
**Plan:** [Starter/Explorer/Pro/Enterprise]
**Date:** [YYYY-MM-DD]

### Issue Description
[One paragraph describing what's broken]

### Impact
- Rows affected: [count]
- Duration: [how long has this been happening]
- Credits impacted: [estimated wasted credits]

### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Expected result vs actual result]

### Evidence
- Table URL: [link to affected Clay table]
- Screenshot of error cells: [attached]
- Column configuration: [which enrichment, which provider]
- Sample input data that fails: [3-5 rows]
- Sample input data that works: [3-5 rows for comparison]

### What I've Already Tried
1. [Reconnected provider API key]
2. [Tested with different input data]
3. [Checked Clay status page — no incidents reported]
4. [Tested provider API independently — works fine]

### Environment
- Browser: [Chrome/Firefox/Safari + version]
- Plan tier: [with credit balance]
- Provider connections: [list connected providers]

Submit at: https://community.clay.com or support@clay.com

Error Handling

Issue	Cause	Solution
Intermittent enrichment failures	Provider rate limiting	Reduce concurrent rows, add delay
All rows failing suddenly	Provider API key expired	Reconnect in Settings > Connections
Partial data returned	Provider has limited coverage	Add waterfall fallback provider
HTTP API column timeout	Target API slow	Increase timeout or process async
Claygent blocked by website	Bot protection	Use Navigator mode or different data source

Resources

• Clay Community Support
• Clay University

Next Steps

For high-volume scaling, see clay-load-scale.