RunComfy API Docs

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

Exit codes

The CLI uses sysexits.h-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)
`66`	`EX_NOINPUT`	a local input file doesn’t exist (`--input-file`, `train submit --config`, an upload path)
`69`	`EX_UNAVAILABLE`	upstream 5xx
`75`	`EX_TEMPFAIL`	retryable: 408, 429, network timeout, a training job that stopped before finishing
`77`	`EX_NOPERM`	auth: 401, 403, not signed in, token rejected
`1`	unclassified	anything else

runcomfy run ... || case $? in
  77) echo "auth failed; refresh login" ;;
  75) echo "transient; retry"          ;;
  *)  echo "permanent failure"         ;;
esac

Common errors

Exit code 77. No token in RUNCOMFY_TOKEN env, no token file at <config_dir>/token.json, no legacy macOS file. Run runcomfy login or set 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.

`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 300 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.

`pass --overrides / --overrides-file ... or --workflow-file`

Exit code 65. Caught client-side: the Serverless inference endpoint rejects an empty body, so deployments run needs the inputs to send. Run runcomfy deployments get <id> --include-payload to see the workflow’s node IDs, input names, and default overrides, then key your --overrides by node ID.

`training job ... did not finish`

Exit code 75. A training job reported STOPPED, but its step progress stopped short of the total or its result carried an error — typically a spot preemption or a reclaimed server. The checkpoints produced so far are still available via train result; continue from the latest one with train resume <job_id>, which reuses the same job id.

`refusing to delete ... without confirmation`

Exit code 64. deployments delete and datasets delete are permanent, so in a non-interactive shell (CI, a pipe, an agent) they refuse unless you pass --yes. On a terminal they prompt instead.

`Skipped N URL(s) outside trusted hosts`

Not an error — the run succeeded. The CLI only downloads from RunComfy CDN hosts (*.runcomfy.net, *.runcomfy.com), including across redirects, so that a compromised or adversarial model output can’t make it fetch arbitrary content. Any other URL in the result is printed but not fetched; copy it yourself if you trust it.

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

Exit code 1. Expected when you Ctrl-C during runcomfy run or deployments run. The CLI also tries to cancel the remote request before exiting — if the cancel call itself failed, or the request was already running (the Model API only cancels queued requests), you’ll see a line saying so, with the id to retry or to fetch later with runcomfy result <id>. train submit --wait and datasets upload --wait behave differently on purpose: Ctrl-C there stops watching but leaves the remote work running, so an accidental keystroke can’t throw away hours of training.

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):

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

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

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
Include: runcomfy --version output, full command, full stderr, OS/arch (uname -a).

Getting Started

Reference

Troubleshooting

Exit codes

Common errors

`authentication failed — token rejected by server`

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

`input did not match the model's schema`

`rate limited; retry in a moment`

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

`prompt too long` / unexpected truncation

`pass --overrides / --overrides-file ... or --workflow-file`

`training job ... did not finish`

`refusing to delete ... without confirmation`

`Skipped N URL(s) outside trusted hosts`

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

Behind a corporate proxy

Pipe and CI gotchas

Verbose / trace logging

Checking the version

Reporting bugs

​Exit codes

​Common errors

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

​authentication failed — token rejected by server

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

​input did not match the model's schema

​rate limited; retry in a moment

​is not a valid model_id (expected slash-separated)

​prompt too long / unexpected truncation

​pass --overrides / --overrides-file ... or --workflow-file

​training job ... did not finish

​refusing to delete ... without confirmation

​Skipped N URL(s) outside trusted hosts

​request cancelled (after Ctrl-C)

​Behind a corporate proxy

​Pipe and CI gotchas

​Verbose / trace logging

​Checking the version

​Reporting bugs

Exit codes

Common errors

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

`authentication failed — token rejected by server`

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

`input did not match the model's schema`

`rate limited; retry in a moment`

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

`prompt too long` / unexpected truncation

`pass --overrides / --overrides-file ... or --workflow-file`

`training job ... did not finish`

`refusing to delete ... without confirmation`

`Skipped N URL(s) outside trusted hosts`

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

Behind a corporate proxy

Pipe and CI gotchas

Verbose / trace logging

Checking the version

Reporting bugs