# Tracetoon errors and exit codes (for agents)

<!-- Generated by scripts/agent-surfaces.ts from src/commands/exitCodes.ts. Do not edit by hand. -->

With `--json`, a failed command prints one JSON object on stdout:

```json
{
  "schemaVersion": 1,
  "error": "gh pr create failed: ...",
  "errorCode": "GH_NOT_AUTHENTICATED",
  "fix": "gh auth login",
  "retryable": false,
  "humanRequired": true
}
```

`error` is the message, as before. Branch on `errorCode`; it is stable.
`humanRequired` means only the user can fix it: show them `fix` and wait.
`retryable` means the same command may work if you run it again later.
Successful JSON objects also carry `schemaVersion`; JSON arrays (such as
`tracetoon integrations --json`) do not.

## Exit codes

| Code | Meaning | What to do |
| --- | --- | --- |
| 0 | Success |  |
| 1 | Error (the message says why) | Read `errorCode` and `fix`; fix and rerun |
| 2 | Unknown command or option, or a missing argument | Check `tracetoon commands --json`, then rerun |
| 3 | Launcher found no runtime | Ask the user, then rerun with `TRACETOON_ALLOW_DOWNLOAD=1` |
| 4 | Image route needs consent | Ask the user; add `--consent` only after they agree |
| 5 | No approved image route, or `doctor --probe --strict` found unknown log records | Offer the printed options, or skip the comic |
| 6 | Only the user can fix it (install or sign in to `gh`, grant access), or `doctor --strict` found a failed required check | Show the user `fix`; rerun after they act |
| 7 | GitHub or the network failed or rate-limited the request | Wait a little, then rerun the same command |
| 10 | `update --check --exit-code`: a newer release exists | Tell the user; update only if they ask |

## Error codes

| errorCode | Exit | Meaning | Fix | Retryable | Needs the user |
| --- | --- | --- | --- | --- | --- |
| `ERROR` | 1 | Any error without a more specific code |  | no | no |
| `USAGE` | 2 | Unknown command or option, or a missing argument | tracetoon commands --json | no | no |
| `NOT_A_GIT_REPO` | 1 | The command must run inside a git repository | cd into the repository, then rerun | no | no |
| `RUN_NOT_FOUND` | 1 | No Tracetoon run, or not the one named by `--run` | tracetoon prepare --json | no | no |
| `RUN_OTHER_WORKTREE` | 1 | The run belongs to another worktree or branch | Switch to that checkout, or pass another --run | no | no |
| `NOTHING_RENDERED` | 1 | Publishing needs a render first | tracetoon render --json | no | no |
| `BRANCH_NOT_PUSHED` | 1 | With `--no-push`: GitHub does not have the rendered revision | tracetoon publish --push | no | no |
| `PR_EXISTS` | 1 | A PR Tracetoon did not render already exists for this branch and base | tracetoon context --json, then render and publish again (it updates that PR) | no | no |
| `GH_MISSING` | 6 | The GitHub CLI (`gh`) is not installed | Install the GitHub CLI: https://cli.github.com | no | yes |
| `GH_NOT_AUTHENTICATED` | 6 | `gh` is not signed in, or its token was refused | gh auth login | no | yes |
| `GH_FAILED` | 1 | A `gh` call failed for another reason (the message has its output) |  | no | no |
| `GITHUB_UNREACHABLE` | 7 | GitHub could not be reached, timed out or rate-limited the call | Rerun the same command in a minute | yes | no |
| `CONSENT_REQUIRED` | 4 | Sending comic prompts to this image route needs the user’s agreement | Ask the user; rerun with --consent only after they agree | no | yes |
| `NO_IMAGE_ROUTE` | 5 | No approved image route can draw the comic | Offer the printed options, or skip the comic | no | yes |
| `COMIC_UNEXPLAINED` | 1 | A comic was expected and an image route could draw it, but none was drawn or skipped with a reason | Draw it (SKILL step 5), or `tracetoon comic skip --reason "<why>"`, then render again | no | no |
| `UPDATES_DISABLED` | 1 | `TRACETOON_DISABLE_UPDATES=1` is set here |  | no | no |
| `UPDATE_LOOKUP_FAILED` | 7 | The release list could not be fetched | Rerun the same command in a minute | yes | no |
| `SKILL_SOURCE_NOT_FOUND` | 1 | `setup` found no skill folder shipped with this runtime | Follow docs/agents/install.md | no | no |
