> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiroleague.com/llms.txt > Use this file to discover all available pages before exploring further. # Errors & exit codes > How hirotm reports failures: exit codes, stderr JSON, and stable code strings for scripts and agents. When **`hirotm`** fails, it exits with a **non-zero status**. With the default global **`--format ndjson`**, stderr is **JSON**: an object that always includes **`error`** (a short human-readable message). It usually includes **`code`** (a stable machine-readable string) and sometimes **`retryable`**, **`hint`**, **`status`**, **`url`**, or extra fields that help you fix the command. With **`--format human`**, the same information is printed as **plain text** on stderr (not JSON). Use **exit code** (`$?` in shells) for coarse decisions, and **`code`** when you want a precise reason without parsing text. Success stdout follows [global **`--format`**](/task-manager/cli/cli-commands#response-format) (**`ndjson`** vs **`human`**). Failures use stderr; **`ndjson`** → JSON payload, **`human`** → plain text. ## Exit codes | Code | When it happens | What to do | | ------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **0** | Command succeeded | Parse stdout per [Response format](/task-manager/cli/cli-commands#response-format): default **`ndjson`** (line-oriented lists, single-line JSON for writes) or **`human`** (tables / labeled text). | | **1** | Generic failure, many **5xx** API errors, rate limits, or other unmapped HTTP cases | Read `error` and `code`. If `retryable` is true, a short backoff may help. | | **2** | Wrong or incomplete **command line** (missing flags, bad values before the API is called) | Fix flags and arguments; do not retry the same line unchanged. | | **3** | **Not found** (often API **404**), or a path / id that does not exist locally (for example a missing file or release id) | Refresh ids or slugs (`boards list`, `boards describe`), or fix file paths. | | **4** | **Forbidden** — CLI policy or **403**; you are not allowed to do this | Change access in the app; do not keep retrying writes. | | **5** | **Conflict** — **409** (duplicate or conflicting state) | Adjust idempotency: skip create, pick another name, or resolve the conflict in the app. | | **6** | **Unreachable** — no HTTP response (server down, connection refused, etc.) | Start the app or run the **`hint`** command (often `hirotm server start`), and verify **`--dev`** and **`--profile`** match the running server, and that **`port`** in that profile’s **`config.json`** matches the process you expect. | | **7** | **Timeout** — API request timed out, or the server did not become healthy in time | Retry after a delay; check load and logs. | | **8** | **Version mismatch** — reserved for future CLI/API compatibility checks | Update Task Manager or the CLI per the message. | | **9** | **Bad request** — API **400** / **422** (validation or bad body) | Fix parameters or payload shape; different from “not found”. | | **10** | **Unauthenticated** — **401** | Configure CLI access / API key in the app when that flow exists. | ## Fields on stderr | Field | Meaning | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | **`error`** | Human-readable summary (always present). | | **`code`** | Stable identifier; prefer this in automation. | | **`retryable`** | If `true`, a later retry may succeed (timeouts, some server errors). | | **`hint`** | Optional copy-paste recovery (for example how to start the server). | | **`status`** | HTTP status when the failure came from the API. | | **`url`** | Request URL that failed (when applicable). | | **`serverCode`** | If the API sent its own `code` field, it is preserved here while **`code`** stays the normalized CLI value. | ## Common `code` values (from the API) These appear when the CLI talked to the server and got an HTTP error: | `code` | Typical meaning | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bad_request` | Validation or malformed input (**400**, **422**). | | `unauthenticated` | Missing or invalid credentials (**401**). | | `auth_cli_key_required` | The server profile has `require_cli_api_key: true` and the request did not include an `Authorization: Bearer …` header. Mint a key with `hirotaskmanager server api-key generate` and put it in the active profile's `api_key`, or pass `--api-key` per command. See [Server operations → CLI API keys](/task-manager/cli/server#cli-api-keys). | | `auth_invalid_cli_key` | A CLI API key was sent but did not match any active key on the server (revoked or wrong). Re-issue or paste the correct key. | | `forbidden` | Not allowed for this board / CLI policy (**403**). | | `not_found` | Board, task, list, or route does not exist (**404**). | | `conflict` | Duplicate or state conflict (**409**). For example, creating or renaming a **release** to a name that already exists on that board returns **409** (not **400**), so **`hirotm`** exits **5** with this `code`. | | `request_timeout` | HTTP **408** (rare) or aligned server timeout. | | `version_mismatch` | **426** — upgrade path may be required later. | | `rate_limited` | **429** — slow down and retry. | | `internal_error` | **5xx** — server-side problem; may be `retryable`. | | `http_error` | Other HTTP status mapped to exit **1**. | ## Common `code` values (before the API) These are checked locally when your flags or files are wrong: | `code` | Typical meaning | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `missing_required` | Required argument or option omitted. | | `invalid_config` | A profile's `config.json` failed validation (wrong fields for the role, public bind without a key, missing `api_url`/`api_key` on a client profile, etc.). The error names the offending field and profile path. See [Profiles → Validation rules](/task-manager/hiro-developers/profiles#validation-rules-enforced-when-the-config-is-loaded). | | `invalid_value` | Bad number, port, id, or similar. | | `mutually_exclusive_options` | Conflicting flags (for example `--color` and `--clear-color`). | | `conflicting_input_sources` | More than one of flag / file / stdin for the same input. | | `conflicting_clear_with_input` | `--clear-*` combined with a value for the same field. | | `invalid_json` | File or stdin was not valid JSON where JSON was expected. | | `invalid_input_shape` | JSON was valid but not the expected array/object shape. | | `no_update_fields` | An update command had nothing to change. | | `release_not_found_by_name` | `--release` name does not exist on that board. | | `emoji_validation_failed` | `--emoji` value was rejected. | ## Connection and server process | `code` | Typical meaning | | ---------------------- | ---------------------------------------------------------------------- | | `server_unreachable` | Could not open an HTTP connection; check that Task Manager is running. | | `request_timeout` | A request over the network exceeded the CLI timeout. | | `server_start_timeout` | `server start` waited for health but the API did not respond in time. | | `server_exited` | Foreground server child exited with an error. | | `no_managed_server` | `server stop` had no pid file for this profile. | | `stale_pid` | Recorded background pid was dead; file was cleared. | | `signal_failed` | Could not send stop signal to the recorded process. | ## Other | `code` | Typical meaning | | ----------------------- | -------------------------------------------------------------------------------------- | | `file_not_found` | A **`--body-file`**, **`--description-file`**, or similar path does not exist. | | `response_inconsistent` | Rare: the server response did not contain an entity the CLI expected after a mutation. | | `internal_error` | Unexpected failure inside the CLI (including unknown errors). | | `confirmation_required` | Add **`--yes`**. | | `confirmation_declined` | Declined at prompt. | ## Example (stderr only) ```json theme={null} { "error": "Board not found", "code": "not_found", "status": 404, "url": "http://127.0.0.1:3001/api/boards/missing-slug" } ``` ## Related * [hirotm CLI](/task-manager/cli/cli-commands) — global options and command index * [Concepts](/task-manager/get-started/concepts) — boards, lists, tasks, Trash * [CLI access policy](/task-manager/cli/cli-access-policy) — why **`forbidden`** may appear