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
set -euo pipefail
echo "=== Layer Isolation Test ==="
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"
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
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:
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:
Step 3: Debug HTTP API Column Issues
async function debugHTTPAPIColumn(
url: string,
method: string,
headers: Record<string, string>,
body: Record<string, string>,
sampleRow: Record<string, string>,
): Promise<void> {
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(, .(resolvedBody));
res = (resolvedUrl, {
method,
: { ...headers, : },
: method !== ? resolvedBody : ,
});
.(, res.);
.(, res.());
}
(
,
,
{ : },
{ : , : },
{ : , : },
);
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:
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
Next Steps
For high-volume scaling, see clay-load-scale.
