$ man clay-wiki/troubleshooting

Eighty percent of Clay issues fall into four buckets: (1) enrichment providers returning empty results, (2) Claygent hallucinating or timing out, (3) credit burn from misconfigured waterfalls, and (4) rate limits on HTTP columns. If your table is broken, check these four things first. Most of the time, it's one of them. The other 20% is usually a table architecture problem — you built the flow wrong, and the fix isn't a band-aid, it's a redesign.

PATTERN

When an enrichment column returns blanks, work through this checklist: (1) Check the input column — is the email/domain/name actually populated for those rows? Empty input → empty output. (2) Check the provider — some providers have better coverage for certain regions or company sizes. Apollo is strong for US tech. Prospeo has good European coverage. (3) Check your waterfall — if you're using a waterfall and the first provider fails, does it actually fall through to the next? Test with 5 rows manually. (4) Check rate limits — some providers throttle after X requests. If the first 50 rows work and then everything goes blank, you're being rate-limited. Space out your runs. (5) Check credits — if you're out of credits, enrichments silently fail. Check your credit balance before investigating anything else.

PATTERN

Claygent is powerful but fragile. Common failure modes: (1) Hallucination — it makes up data that looks real. Fix: run a 5-row sample first and manually verify every field against the source. If it hallucinates on 1/5, it'll hallucinate on 100/500. (2) Timeout — it tries to browse a page that's too large or takes too long to load. Fix: give it more specific instructions. Instead of "summarize this website," say "read the /about page and extract the company's founding year and employee count." (3) JSON schema violations — you asked for structured output but it returned prose. Fix: include the exact JSON schema in your prompt and add "Return ONLY valid JSON, no explanations." (4) Token limit — the page content exceeds the context window. Fix: target specific pages, not entire sites. Use FireCrawl to get clean markdown first if needed.

ANTI-PATTERN

If your credits are disappearing faster than expected: (1) Check for enrichment columns running on every row, including rows that already have data. Add a condition: only enrich if the target column is empty. (2) Check for duplicate enrichments — same contact getting enriched in multiple tables. Dedupe by domain at the account level first. (3) Check your waterfall — if the waterfall tries all 5 providers on every row (even when the first one succeeds), you're burning 5x credits. The waterfall should stop at the first valid result. (4) Check Claygent — it costs more credits than simple enrichments. If you're running Claygent on 1,000 rows for something a formula could do, you're wasting money. My rule: if time spent avoiding credits exceeds the credit cost, use the credits. But if credits are burning because of misconfiguration, fix the plumbing.

PATTERN

HTTP columns hit APIs directly, which means you're subject to rate limits. Symptoms: first N rows return data, then everything after returns errors or blanks. Fixes: (1) Add a delay between rows — Clay lets you configure run speed. Slow it down. (2) Batch your runs — don't run 5,000 rows at once. Run 500, wait, run 500 more. (3) Check API documentation for rate limits — some APIs allow 100 requests/minute, others allow 10. Match your Clay run speed to the API's limit. (4) Use Clay's built-in rate limiting if available for the provider. (5) For critical APIs, consider routing through a proxy that handles backoff automatically. This is especially important for MX record lookups and custom API endpoints.

ANTI-PATTERN

Sometimes the table isn't broken — it's badly designed. Signs of architecture problems: (1) You have 40+ columns and can't find anything. Split into account table and contact table. (2) You're enriching company data on every contact row. Stop. Create an account table, dedupe by domain, enrich once, write back with lookup columns. (3) Your scoring column depends on data from 15 other columns and sometimes they're not all populated. Build scoring as the last step, after all enrichment is complete. (4) You're using one table for sourcing, enrichment, scoring, AND routing. That's too much. Source → enrich → score → route should flow across 2-3 tables.

PRO TIP

Most issues are user error or architectural. But sometimes Clay itself has bugs. Escalate when: (1) An enrichment provider that was working yesterday returns errors on every row today — provider-side outage. (2) Credit charges don't match your usage — billing discrepancy. (3) A column runs but the output is corrupted or truncated — platform bug. (4) The UI freezes or tables won't load — infrastructure issue. Before you escalate, document: what you tried, what you expected, what happened instead, and screenshot the error. Clay support is responsive but they need specifics. "It's broken" gets a slow response. "Apollo enrichment on Table X returns 'provider_error' for all rows since 2pm, previously working" gets a fast one.