Skip to main content

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.

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.
CodeNameWhen
0success
2clap parse errorbad CLI args (missing required, unknown flag)
64EX_USAGEusage error (e.g. model_id without a /)
65EX_DATAERRbad input data — JSON parse error, schema mismatch (API 422/400)
69EX_UNAVAILABLEupstream 5xx
75EX_TEMPFAILretryable: 408, 429, network timeout
77EX_NOPERMauth: 401, 403, not signed in, token rejected
1unclassifiedanything else
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 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 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>.

​
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