# Common gotchas

Silent-failure footguns and frequently confused command pairs across the Cargo CLI. Skim before designing a new workflow or debugging unexpected empty results.

| Gotcha                             | Detail                                                                                                                                                                                                                                        |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conjonction` spelling             | Filter JSON uses `conjonction` (not `conjunction`). This is intentional. A typo here fails silently — no records returned.                                                                                                                    |
| `run create` vs `batch create`     | `run create` only works with **tool** workflows. Using a play's `workflowUuid` returns `playNotCompatible`.                                                                                                                                   |
| `--model-uuid` vs `--segment-uuid` | `segment fetch` and `segment download` require `--model-uuid`. Get it from `segment list` → `.modelUuid`.                                                                                                                                     |
| Storage query table names          | `storage query execute` and `storage query download` reference tables as `<datasetSlug>.<modelSlug>` (e.g. `default.companies`).                                                                                                              |
| Token shown once                   | API token values are only returned at creation. Store immediately. `workspaceManagement token create` requires `--name` (no more `--from-user`).                                                                                              |
| Invoice amounts in cents           | `subscription get-invoices` returns `amount` in cents. Divide by 100.                                                                                                                                                                         |
| Plays vs tools                     | **Play** = reacts to data changes (segment-driven). **Tool** = triggered on demand (manual, API, cron).                                                                                                                                       |
| Batch data kinds                   | Play workflows accept: `segment`, `change`, `filter`, `recordIds`. Tool workflows accept: `file`, `records`.                                                                                                                                  |
| Third-party connector rate limits  | Only `kind: "connector"` nodes (Clearbit, HubSpot, etc.) have rate limits — native nodes do not. Errors grow silently as the batch runs. Start at 1 record, then 50, then 500 before full-scale. Add `retry` with backoff to connector nodes. |
| Template expressions fail silently | A `{{nodes.foo.bar}}` referencing a missing path resolves to `undefined` (no error) and the run still reports `success` — so branches take the wrong path and end-node values come out empty, silently. Verify the real shape with `run get <uuid>` → `runContext.<slug>` (node-level outputs **are** returned by the CLI). Agent output is nested under `.answer`. |
| Group results are an array         | A `group` node's output is an array of per-iteration `end` outputs: `{{nodes.<groupSlug>[0].<field>}}`. There is **no `.results` wrapper**, and `.map(x => …)` arrow callbacks aren't supported in expressions. |
| Context survives a `delay`         | Prior node outputs are **not** wiped by a `delay` — the run context is checkpointed (as JSON) and restored. The catch is JSON-serializability: store anything needed post-delay in a `variables` node, not a `python` node's `result`. |
| `context runtime execute` is ephemeral | `context runtime execute` runs commands in the sandbox but **does not push** any file changes. Use `runtime write` / `runtime edit` for persistent edits to the context repo.                                                             |
| `context runtime edit` must match exactly once | `--old-string` must occur exactly once in the file. Whitespace counts — read the file first and copy the substring verbatim. For multi-spot changes, do multiple targeted edits or use `write` to overwrite the whole file.       |