{"id":103337,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:21.096Z","digest":"419c10aef98bdd83e7c7833f670061237010a61323365fead9edeabedb60aca4","against":null,"payload":{"description":"Clay tables — sweep a table for errored rows and report grouped by root cause (not a specific record). Use when the user asks \"what's erroring in {table}?\", \"show failed rows\", or \"is {action} failing?\".","included_files":[],"name":"tables-error-sweep","skill_md_contents":"---\nname: tables-error-sweep\ndescription: Clay tables — sweep a table for errored rows and report grouped by root cause (not a specific record). Use when the user asks \"what's erroring in {table}?\", \"show failed rows\", or \"is {action} failing?\".\nallowed-tools: Read\n---\n\n# Error sweep\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\n**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.\n\nOnly **`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.\n\n## 1. Understand the table first\n\nBefore sweeping, learn what _can_ error.\n\n1. Resolve the table as in the tables entry-point skill (\"Finding a table\").\n2. Run **`clay tables get <tableId>`** and note its `type` and `rowCount`.\n3. **`clay tables columns get <tableId>`** (shape in the command's `--help`). Build the picture:\n   - Which columns are `type: \"action\"` — these are the ones that fail. Keep a `f_id → name` map for readable reporting.\n   - 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).\n4. **If the table has no action columns**, errors are unlikely — say so, and confirm with a one-page scan (step 3) before concluding.\n\n## 2. Settle the scope: one column or general\n\n- **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.\n- **User asked generally** (\"what's erroring?\") → sweep across **any** column in `error`.\n- **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.\n\n## 3. Find the errored rows\n\nCell 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:\n\n**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:\n\n```bash\nclay 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) ]}'\n```\n\nContinue 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.\n\n**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`:\n\n```bash\necho '{\"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) ]}'\n```\n\n**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.\n\n```bash\n# One page: errored rows and which columns errored (add more pages via .cursor)\nclay 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) ]}'\n```\n\nPaginate 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.\n\n## 4. Read the error messages\n\nOnly 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`:\n\n```bash\nclay tables rows get <tableId> <rowId> | jq '.cells | to_entries | map(select(.value.status == \"error\")) | map({col: .key, msg: .value.error})'\n```\n\nRespect the rate limits — batch `rows get` calls in small groups (≈3) and back off on exit 4 (`rate_limited`, honor `details.retryAfter`).\n\n**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.\n\nA 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.\n\n## 5. Diagnose — group by root cause\n\nAggregate 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:\n\n| Message pattern                                         | Likely root cause                                                                                             | Direction                                                                               |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| \"rate limit\", \"429\", \"quota\", \"throttled\"               | Provider throttling on this action                                                                            | Usually transient — retriable; check `customRateLimitRules` / `batchRunSettings`        |\n| \"invalid api key\", \"unauthorized\", \"auth\", \"credential\" | The action's connected account (`authAccountId`) is bad/expired                                               | Reconnect the integration account                                                       |\n| \"no {x} found\", \"no input\", \"missing\", empty-input      | An **upstream** column produced nothing, so this action had no usable input                                   | Trace the input (`inputsBinding` → upstream column) — hand to `/tables-value-trace`     |\n| \"run condition not met\" / conditional gate              | **Not a real failure** — `conditionalRunFormulaText` evaluated falsy and the action was intentionally skipped | Usually expected; note a gated skip more often shows as `empty` than as an errored cell |\n| provider-specific error text                            | The downstream provider rejected the request                                                                  | Read the message literally; often a data-quality issue in the input                     |\n\nSeparate **genuine failures** from **expected gating**. Don't let conditional skips inflate the failure count — call them out separately.\n\n## 6. Report\n\nLead with the count and the breakdown by cause; put the analysis, not the raw rows, front and center.\n\n```\nLead Enrichment — 37 rows with errored action cells (all 1,543 rows scanned; 12 fetched for messages).\n\nBy cause:\n  • 28 — Enrich Company: \"Rate limit exceeded for Clearbit API\"\n         → provider throttling. Transient/retriable; consider a rate-limit rule or smaller batches.\n  • 6  — Enrich Person:  \"No email found for input\"\n         → upstream \"Find Email\" returned nothing, so Enrich Person had no email to use.\n            Root cause is upstream, not this action. (/tables-value-trace Find Email to confirm.)\n  • 3  — Enrich Person:  \"Invalid API key\"\n         → the connected account for this action is expired. Reconnect it.\n\nRoot cause: the dominant failure (28/37) is Clearbit throttling on Enrich Company —\nretriable and not a data problem. A secondary cluster traces back to Find Email\nproducing no email upstream.\n```\n\nIf 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.\n\n## Hand-offs\n\n- A specific errored row the user wants to understand end-to-end → `/tables-trace`.\n- An error that traces to a bad/missing **input** → `/tables-value-trace` (walk `inputsBinding` upstream).\n- \"Rows aren't appearing\" with no errors found → `/tables-capacity`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}