Error sweep

Use when: "what's erroring in {table}?", "show failed rows", "is {action} failing?" — a table-level question with no specific record in hand. Goal: find the errored rows, read their messages, and report grouped by root cause, not row by row.

Only action columns can be in error. basic and source columns don't error (a formula-backed basic can, rarely), so the sweep is about action columns.

1. Understand the table first

Before sweeping, learn what can error.

1. Resolve the table as in the tables entry-point skill ("Finding a table").
2. Run clay tables get <tableId> and note its type and rowCount.
3. clay tables columns get <tableId> (shape in the command's --help). Build the picture:
   • Which columns are type: "action" — these are the ones that fail. Keep a f_id → name map for readable reporting.
   • For each action column, note authAccountId (auth-related failures), conditionalRunFormulaText (a gate — a skipped action usually shows as empty, not a failure), and inputsBinding (what feeds it — needed if a failure turns out to be a bad/missing input).
4. If the table has no action columns, errors are unlikely — say so, and confirm with a one-page scan (step 3) before concluding.

2. Settle the scope: one column or general

• User named a specific action ("is Enrich Company failing?") → map that name to its f_id from step 1 and scope the client-side filter (step 3) to that column.
• User asked generally ("what's erroring?") → sweep across any column in error.
• Ambiguous name / multiple action columns match → show the action columns and let the user pick, or default to the general sweep and break the results down by column.

3. Find the errored rows

Cell status isn't filterable server-side on either path, so a sweep pages through the rows and picks out the errored cells client-side. Choose the scan by table type, then whether a normal table is query-enabled:

Bulk enrichment table → inspect one retained-row sample. Do not use the query-enabled path or attempt a full sweep. These tables return truncated: true with one unfiltered, cursorless sample of at most 20 currently retained rows, and completed rows may already have been deleted:

clay tables rows list <tableId> --limit 20 | jq '{truncated, errored: [ .data[] | { id, cols: (.cells | to_entries | map(select(.value.status == "error")) | map(.key)) } | select(.cols | length != 0) ]}'

Continue to step 4 for those row ids. Report the number of retained rows inspected and call the result sample-only; never claim a full-table error count. If the sample is empty, say that no retained rows were available to inspect, not that the table has no errors.

Query-enabled normal table → scan with tables query. Each cell comes back with its status and, on an error, its error message — so one pass finds the failures and their messages (skip step 4). Paginate via the top-level cursor:

echo '{"tables":[{"id":"t_abc123"}]}' | clay tables query --query - --limit 100 | jq '{next: .cursor, errored: [ .data[] | [ to_entries[] | select(.value.status == "error") | { col: .key, msg: .value.error } ] | select(length != 0) ]}'

Not query-enabled → walk clay tables rows list pages and filter client-side on cell status (list output carries every cell's status); the full messages then come from rows get (step 4). Don't enable sync just for a sweep — it's an escalation that costs a limited slot.

# One page: errored rows and which columns errored (add more pages via .cursor)
clay tables rows list <tableId> --limit 100 | jq '{next: .cursor, errored: [ .data[] | { id, cols: (.cells | to_entries | map(select(.value.status == "error")) | map(.key)) } | select(.cols | length != 0) ]}'

Paginate via the top-level cursor (pass it back with --cursor) until it's absent. A listing covers the rows that existed when its first page was fetched, so the walk terminates even on an actively-importing table. Use rowCount from clay tables get to budget: a full sweep of a big table is rowCount / limit calls under the rate limit — for very large tables, sample pages first and say you sampled.

4. Read the error messages

Only needed for the rows list path — if you swept via tables query, the messages are already in that result, so skip to step 5. The rows list scan tells you which rows and columns erred, but its error strings are abbreviated labels; the full messages live on clay tables rows get:

clay tables rows get <tableId> <rowId> | jq '.cells | to_entries | map(select(.value.status == "error")) | map({col: .key, msg: .value.error})'

Respect the rate limits — batch rows get calls in small groups (≈3) and back off on exit 4 (rate_limited, honor details.retryAfter).

Don't silently cap. If there are many errored rows, you usually don't need to fetch all of them to characterize the failure — fetch until the set of distinct messages stabilizes (new rows stop introducing new messages), then state how many rows you sampled out of the total (rowCount from clay tables get, and the ids you collected). Never imply full coverage when you sampled.

A single row can have multiple errored action cells (general sweep). Capture each errored cell, and map col back to the column name from step 1.

5. Diagnose — group by root cause

Aggregate the {col, msg} pairs across rows. Group by message (normalize near-identical messages — strip row-specific values like emails or ids so "No email for john@x" and "No email for jane@y" collapse to one cause). For each group, infer the cause using what step 1 told you:

Separate genuine failures from expected gating. Don't let conditional skips inflate the failure count — call them out separately.

6. Report

Lead with the count and the breakdown by cause; put the analysis, not the raw rows, front and center.

Lead Enrichment — 37 rows with errored action cells (all 1,543 rows scanned; 12 fetched for messages).

By cause:
  • 28 — Enrich Company: "Rate limit exceeded for Clearbit API"
         → provider throttling. Transient/retriable; consider a rate-limit rule or smaller batches.
  • 6  — Enrich Person:  "No email found for input"
         → upstream "Find Email" returned nothing, so Enrich Person had no email to use.
            Root cause is upstream, not this action. (/tables-value-trace Find Email to confirm.)
  • 3  — Enrich Person:  "Invalid API key"
         → the connected account for this action is expired. Reconnect it.

Root cause: the dominant failure (28/37) is Clearbit throttling on Enrich Company —
retriable and not a data problem. A secondary cluster traces back to Find Email
producing no email upstream.

If a normal-table sweep found no errored cells, report that nothing is currently erroring — and if the underlying complaint was "rows aren't appearing," redirect to /tables-capacity (a full table looks like a failure but produces no errored cells). For a bulk enrichment sample, report only that no errors appeared in the retained rows inspected; an empty sample proves neither that the table has no errors nor that it has a capacity problem.

Hand-offs

• A specific errored row the user wants to understand end-to-end → /tables-trace.
• An error that traces to a bad/missing input → /tables-value-trace (walk inputsBinding upstream).
• "Rows aren't appearing" with no errors found → /tables-capacity.