mirror of
https://github.com/getcargohq/cargo-skills.git
synced 2026-09-14 19:17:15 +08:00
Auree Aubert
69f8642cb5
* cargo-analytics 1.5.0: describe what the run exports actually return
`run download` was documented as returning "each run as a JSON object with
status, timing, executions, and runContext.<nodeSlug> containing per-node
outputs". It returns a signed URL to a gzipped CSV with one column per node
slug holding that execution's `title` — the truncated summary the diagnostics
runbooks call "never evidence". No runContext, no executions, not JSON.
- Rewrites the run download section around the real columns, with a warning
to treat it as a status board across runs, not as node output.
- Corrects run download-outputs: --output-node-slug is optional (falls back to
the last executed node), each row is input + output, and without --limit the
file covers every matching run.
- Adds a section answering "can I get runContext for several runs at once" —
you can't: it is a per-run S3 object and run get is the only command that
hydrates it. Orchestration SQL is ruled out explicitly.
- Marks --is-finished broken in the six snippets that taught it; it returns
400 unrecognized_keys on all four run commands. Replaced with
--statuses success,error.
- Fixes the partial-retry pattern in polling.md, which piped run download
stdout into jq '.recordId' — impossible against a signed URL to a gzipped
CSV whose column is _record_id.
- response-shapes.md gains entries for both run exports and corrects batch
download, which also returns {"url": …} rather than streaming to stdout.
- Adds the 500 case to analytics troubleshooting.
Verified against CLI 1.0.52 and the backend source. Underlying defects are
fixed in getcargohq/cargo#5579; these docs describe today's behavior.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Drop the --is-finished caveats; the fix is a backend deploy
The caveats dated the docs against a deploy the bundle can't observe, and my
stated reason for them was wrong: cargo#5579 changes no CLI code for
isFinished (0 occurrences in its packages/cli diff) — the flag was always
sent, the API route schemas rejected it. So the fix lands when the backend
deploys, independent of the cli-version pin.
Examples keep --statuses success,error, which expresses the same filter and
is correct before and after that deploy, so nothing here expires. The specific
400 is replaced by a generic `400 unrecognized_keys` troubleshooting row that
stays useful whatever the flag, and points at report create.
Also drops "until the fix ships" from the 500 row, for the same reason.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Restore --is-finished: it is wider than success+error
Swapping the flag for `--statuses success,error` was semantically wrong, not
just verbose. `isFinished` maps to `finished_at IS NOT NULL`, and cancelled
(cancelRuns.ts:94) and skipped (launchRuns.ts:151) runs stamp finishedAt too.
Skipped is routine — checkToSkipRuns marks records skipped as ordinary dedupe
behaviour — so the substitution would silently under-report on any play that
skips records.
exports.md and run-analytics.md revert to their original content: their
--is-finished examples were correct all along. The run download section now
shows both forms with a note that they are not interchangeable.
The flag still 400s until cargo#5579 reaches production, which is a backend
deploy independent of the CLI release; the generic 400 unrecognized_keys row
in troubleshooting.md covers that window without dating the docs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2.5 KiB
2.5 KiB
Troubleshooting
Common errors and recovery steps for cargo-analytics commands.
General
| Symptom | Cause | Fix |
|---|---|---|
{"errorMessage": "..."} with non-zero exit |
Any CLI error | Read the errorMessage — it usually says exactly what's wrong |
command not found: cargo-ai |
CLI not installed or not in PATH | Run npm install -g @cargo-ai/cli or prefix with npx @cargo-ai/cli |
Unauthorized or Forbidden |
Bad or expired credentials | Re-run cargo-ai login --oauth (browser sign-in) or cargo-ai login --token <token>; verify with cargo-ai whoami |
Run metrics and counts
| Symptom | Cause | Fix |
|---|---|---|
run get-metrics returns empty array |
No runs exist for that workflow/period | Verify the --workflow-uuid; try without date filters to check if any runs exist |
| Error count seems too high | Counting across all time | Scope with --created-after and --created-before for a specific period |
run count returns 0 unexpectedly |
Filter combination too narrow | Remove filters one at a time to isolate which one excludes all runs |
Downloads and exports
| Symptom | Cause | Fix |
|---|---|---|
run download returns empty |
No runs match the filters | Loosen filters — drop the date and status constraints and pass --workflow-uuid alone |
run download returns 500 Internal Server Error |
The workflow resolves to zero active nodes — all archived, or the UUID doesn't exist in this workspace. The export builds one column per node slug, so there is nothing to select | Confirm the UUID with workflow list / play list. Loosening filters won't help; the failure is about the workflow, not the runs |
400 unrecognized_keys: <flag> on a run command |
The CLI offers a flag the API's request schema doesn't accept | Drop the flag and express the filter another way — --statuses success,error covers "finished". Then report it: workspaceManagement report create |
batch download fails with "node not found" |
Wrong --output-node-slug |
Re-run release get <release-uuid> and check nodes[].slug for the correct value |
segment download returns empty |
Wrong model UUID or over-filtered | Verify --model-uuid (not --segment-uuid); try empty filter {"conjonction":"and","groups":[]} first |
| Parse error on filter JSON | Malformed JSON or wrong spelling | Check: it's conjonction (not conjunction); validate JSON syntax; see the cargo-orchestration skill's references/filter-syntax.md |