Troubleshooting
Symptoms matched to exit codes and error codes, what each means, and where to go next.
Use this page when a command fails or results look wrong. In this article, we will run quick checks, then match what you see to the exit code, error code, and detailed article.
Quick checks
postsale doctor --humanpostsale account envpostsale auth status- Capture stdout for data and stderr for errors (
postsale runputs progress on stderr)
Symptoms and what to do
| Symptom | Likely meaning | What to do |
|---|---|---|
Exit 100 / auth_required | Not authenticated | Sign In and Credentials |
Exit 100 / api_key_unsupported | The active credential is an API key and this command needs a login session | auth login, or skip the command on the key; see Use an API key |
Exit 100 / api_key_rejected | The API key lacks a permission (missing_scopes) or was revoked, disabled, or is off-plan | Grant the permission in the Postsale app (about a minute), or issue a new key; logging in does not help |
Exit 78 / terms_acceptance_required | First house/USPS or Shipsurance label: the account owner must accept the carrier's terms | Relay data.accept_url (or the in-app remediation) to the owner; see Shipping, labels and rates |
Exit 101 / subscription_reactivation_required | The subscription is inactive; every billable request answers 402 | The owner reactivates at data.reactivate_url; nothing to retry until then |
Exit 64 / test_label_required | POSTSALE_TEST_LABEL_MODE is set and a shipment in the purchase is not a test shipment | Create the shipment under the mode (it is stamped), or unset the mode for real labels; see Test-label mode |
Exit 64 / confirmation_required | Money or destructive needs auth | Pass --yes or approve at TTY; see Safety |
Exit 64 / swarm_authorization_required | Batch gate (not fixed by --yes alone) | [Parallel batches](../features/parallel batch.md); TTY batch approve or POSTSALE_SWARM_AUTOAUTH=1 only if pre-authorized |
Exit 102 / validation_failed | Bad body / missing weight_unit / dims | Intent builders; read error.details |
Exit 103 / rate_limited | Too many requests | Wait retry_after; see env RPM settings |
Exit 106 / request_timeout | Backend hung | Retry; raise POSTSALE_HTTP_TIMEOUT_MS |
| Exit 75 | Network or doctor pre-flight warnings | Retry; doctor --pre-flight details |
Empty stdout + non-zero on run | Preflight failed (LLM key, bad continue id, config) | Read stderr; no envelope was produced |
| Zero orders, "success" | Filter miss / wrong status | Work queue / empty results |
| Orders found, no shipment fields | Expected domain join | Orders, Shipments, and Labels |
| Thought dry-run wrote nothing | Non-intercepted writes | Dry-run; check confirmed_effects |
| Cheap quote, expensive label | Quote-only dimension estimate | Intent builders |
| Void rejected | Carrier rules | Void and Corrections |
| Unknown continue id | Bad conversation id | postsale conversations |
Agent hosts
Full error.code recovery table: agent/errors.md and AGENTS.md.
Exit codes reference
Additional Reading
On this page
Related