> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runcomfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Common errors, why they happen, and how to fix them.

***

## Exit codes

The CLI uses [`sysexits.h`](https://man.openbsd.org/sysexits.3)-style exit codes so scripts can branch on failure type without parsing strings.

| Code | Name             | When                                                             |
| ---- | ---------------- | ---------------------------------------------------------------- |
| `0`  | success          |                                                                  |
| `2`  | clap parse error | bad CLI args (missing required, unknown flag)                    |
| `64` | `EX_USAGE`       | usage error (e.g. `model_id` without a `/`)                      |
| `65` | `EX_DATAERR`     | bad input data — JSON parse error, schema mismatch (API 422/400) |
| `69` | `EX_UNAVAILABLE` | upstream 5xx                                                     |
| `75` | `EX_TEMPFAIL`    | retryable: 408, 429, network timeout                             |
| `77` | `EX_NOPERM`      | auth: 401, 403, not signed in, token rejected                    |
| `1`  | unclassified     | anything else                                                    |

```bash theme={null}
runcomfy run ... || case $? in
  77) echo "auth failed; refresh login" ;;
  75) echo "transient; retry"          ;;
  *)  echo "permanent failure"         ;;
esac
```

***

## Common errors

### `not signed in — run \`runcomfy login\` first\`

**Exit code 77**. No token in `RUNCOMFY_TOKEN` env, no token file at `<config_dir>/token.json`, no legacy macOS file. Run [`runcomfy login`](/cli/commands#login) or set [`RUNCOMFY_TOKEN`](/cli/auth#ci--container-env-var-runcomfy_token).

### `authentication failed — token rejected by server`

**Exit code 77**. Server returned 401 — the token was once valid but isn't anymore (revoked, rotated, or wrong). Run `runcomfy login` to mint a fresh one, or rotate `RUNCOMFY_TOKEN` to a current value from your [Profile](https://www.runcomfy.com/profile).

### `model `xxx` not found. Verify the model_id at https://www.runcomfy.com/models`

**Exit code 65**. The Model API doesn't have a model at that path. Common causes:

* Typo (e.g. `flux-1-kontext-pro/edit` vs `flux-1-kontext/pro/edit` — note the slash placement)
* Stale model\_id from a tutorial; the model was renamed or removed

Find the canonical id on the model's page: it's printed prominently above the playground.

### `input did not match the model's schema`

**Exit code 65**. API returned 422 / 400. The CLI sends the JSON body verbatim to the Model API; if a required field is missing or a value is the wrong type, the server rejects it. The error message includes the server's response body (capped at 200 chars).

Open the model's API tab — it lists the Input schema with required fields, types, and defaults. Adjust your `--input` JSON to match.

### `rate limited; retry in a moment`

**Exit code 75**. API returned 429. Retry after a short sleep. RunComfy free-tier accounts share rate limits; pro plans have higher caps.

### `is not a valid model_id (expected slash-separated)`

**Exit code 65**. Caught client-side before the request goes out. `model_id` must contain at least one `/` — that's how Model API paths work. Example: `openai/gpt-image-2/text-to-image`.

### `prompt too long` / unexpected truncation

Most models have a token limit (often 512 or "a few thousand"). The CLI doesn't enforce this — the model server does. Trim your prompt or check the model page for the exact limit.

### `request cancelled` (after `Ctrl-C`)

**Exit code 1**. Expected when you Ctrl-C during `runcomfy run`. The CLI also tries to cancel the remote request before exiting — if the cancel call itself failed, you'll see a warning telling you to retry with [`runcomfy cancel <id>`](/cli/commands#cancel).

***

## Behind a corporate proxy

`reqwest` (the HTTP client) honors the standard `HTTP_PROXY` / `HTTPS_PROXY` env vars automatically. If your proxy intercepts traffic with a custom CA, set `SSL_CERT_FILE=/path/to/ca-bundle.pem`.

To force-bypass the proxy (e.g. for direct LAN access):

```bash theme={null}
NO_PROXY=* no_proxy=* runcomfy run ...
```

Sporadic 403 from `model-api.runcomfy.net` while behind a local proxy (ClashX, Surge, etc.) usually means the proxy is interfering — retry, or temporarily set `NO_PROXY=*` for the call.

***

## Pipe and CI gotchas

* Use `--output json` for any script. Pretty mode emits emoji that mangle `jq` parsing.
* In non-TTY (piped, CI logs), the CLI auto-replaces emoji with `[tag]` — but progress lines still go to stderr. `runcomfy ... 2>/dev/null` is fine.
* `NO_COLOR=1` and `TERM=dumb` both turn off all color and emoji.
* `RUNCOMFY_TOKEN` env wins over the token file. Forgetting to unset it locally after testing CI flows is a common foot-gun.

***

## Verbose / trace logging

```bash theme={null}
runcomfy -v run ...                     # one line per outbound HTTP call
runcomfy -vv run ...                    # add timing
RUST_LOG=reqwest=trace runcomfy ...     # raw reqwest trace (auth header is redacted)
```

***

## Checking the version

```bash theme={null}
runcomfy --version
# runcomfy 0.1.1 (16cc8b8, 2026-04-29)
```

The git short SHA in the parens makes it easy to pin a specific build when filing a bug. If you see `unknown` instead of a sha, you installed from a tarball or `cargo install` — that's fine, just include `--version` output verbatim when reporting issues.

***

## Reporting bugs

* Repo: [runcomfy-com/runcomfy-cli](https://github.com/runcomfy-com/runcomfy-cli)
* Include: `runcomfy --version` output, full command, full stderr, OS/arch (`uname -a`).