Troubleshooting

Separate connection, input, execution and evidence failures before retrying.

Start with the smallest relevant check. Do not restart paid work merely because a summary looks incomplete.

Check identity and connection

synth version
synth status --json
synth task list --json

Status explains local credential selection; the last command tests an authorized remote read. A local signed-in state does not prove remote access. If credentials are expired, reauthenticate. If the endpoint is wrong, first confirm the intended connection with your administrator. Never send credentials to an arbitrary host.

Check inputs without launching the agent

synth agent validate reviewer.json
synth task show <task-ref> --json
synth run start --task <task-ref> --actor @reviewer.json --dry-run --json

Profile validation proves structure, not that an engine will install, a model will be accessible or an output will be useful. Inspect the resolved request, then run one bounded example before launching a large experiment.

Follow the failure to its level

Symptom	Inspect
Run rejected before execution	Selector, profile, plan, authentication and resource validation.
No trial has started	Run and batch state, recorded admission or setup failures.
Trial failed or timed out	Trial details, agent output, phase timing and verifier/judge logs.
Review exists but reward is missing	Required output paths, scoring evidence and reward-file format.
Reward is high but the answer is poor	Rubric, judge calibration and possible reward exploitation.
Training completed trials but made no update	Batch trainability, usable rewards, optimizer events and checkpoint records.
Counts disagree	Planned versus observed units, pagination, missing history and recovered segments.

synth run show <run-id> --json
synth run updates <run-id>
synth run groups <run-id>
synth run trials <run-id>
synth run show <run-id> --trial <trial-id>
synth run checkpoints <run-id>

A list page is not the full population. Follow the pagination options in that command’s help. Do not equate absent history with a count of zero.

Local tools and exports

Install Harbor separately for local Harbor execution. A local profile or interactive coding session uses your machine; it is not the managed task sandbox.

For exports, use a new output directory and inspect the manifest or receipt. If files are missing, preserve the run ID and coverage rather than editing the bundle to appear complete.

Report a useful failure

Include the CLI version, redacted request, service connection, resource ID, idempotency key, request ID, relevant events and the exact observed result. State what you expected and whether the request might already have taken effect. Do not attach credentials, signed URLs or unreviewed private transcripts.