comfy-debug

When something fails on the comfy CLI, **read the JSON envelope first**, act on the `hint`, and only go deeper if needed. This skill is the bottom-up playbook. ## The envelope is the source of truth Every command emits the standard JSON envelope (see core skill). When `error` is present, map `error.code` to a fix below. Three rules: 1. **Map `error.code` to a fix below.** Most codes have a one-line resolution. 2. **`hint` is authoritative.** If it says "run: comfy launch", that's the fix. Don't paraphrase, don't guess. 3. **`details` carries the why.** Look here before scrolling logs. ## Decision tree for common failures ### `server_not_running` (local) ``` comfy launch # start the local server in the foreground # or, for background mode: comfy launch --background ``` If `comfy launch` itself fails: check `comfy --json env` for the resolved interpreter and workspace, and inspect whatever stdout `comfy launch` was attached to. ### `cloud_not_configured` / `cloud_unauthorized` (cloud) ``` comfy cloud login # opens browser, OAuth + PKCE # or, if you already have an API key: comfy cloud set-key --key sk-… # alternative path; API key is a fallback, not an override comfy --json cloud whoami # confirm signed_in: true (auth_method is "oauth" or "api_key") ``` Auth precedence is **env first**: a credential handed in by the environment (`COMFY_CLOUD_AUTH_TOKEN`, then `COMFY_CLOUD_API_KEY`) outranks a live `comfy cloud login` session, which outranks a key saved with `comfy cloud set-key`. Empty or whitespace-only env values count as unset. While an env credential is set the stored session is not refreshed or used. `comfy --json cloud whoami` shows which credential is active in `credential_source`. If a stale session is causing 401s, `comfy cloud logout && comfy cloud login`, or unset the env credential if that is the one being refused. If you're on a custom env (PR preview), set the base URL first: ``` comfy cloud set-base-url https://fe-pr-NNNNN.testenvs.comfy.org ``` **Do not confuse this with `transient_auth` (below).** `cloud_unauthorized` happens before submission (your CLI session); an "Unauthorized" that appears as a *job failure* is the server-side token expiry and re-login does nothing. ### `transient_auth` (cloud job failed with "Unauthorized: Please login first to use this node") An API node's **server-side** session token expired mid-execution. It is transient and has nothing to do with your local credentials — `comfy cloud login` will NOT fix it, and your auth was fine at submit time (often it strikes minutes into a long render, sometimes a whole batch at once). ``` comfy --json run --workflow same_workflow.json --where cloud # just resubmit — succeeds on retry ``` If several jobs from one batch died together with this code, resubmit them all; one retry each is normally enough. ### `workflow_not_api_format` UI-format workflows are converted to API format **client-side** using object_info (no server conversion endpoint exists). If conversion fails with `conversion_error`, re-export via `File > Export (API)` in ComfyUI; if object_info can't be fetched (`cql_no_graph`), retry (it's fetched live — check cloud sign-in/connection) or start a local server. ### `workflow_invalid_json` The file isn't valid JSON. Inspect the first/last 100 bytes — often it's an HTML error page that was saved with `.json`. ### `prompt_rejected` (server returned `node_errors`) The server validated the workflow and rejected nodes. The full per-node error map is in `details.node_errors`. The two most common causes: - **Unknown class_type** → the cloud or local server lacks the custom node. Run: ``` comfy --json nodes search MissingNodeName ``` If `data.count` is 0 — or `data.close_match` is true, meaning the search found nothing and fell back to similarly-named classes — the node is genuinely absent. Then either install via `comfy node install <pkg>` (local) or pick a different workflow (cloud). - **Missing model file** (`ckpt_name`, `lora_name`, `vae_name` not found) → confirm the loader node exists and see its choices: ``` comfy --json nodes show CheckpointLoaderSimple # inputs[].choices lists available checkpoints comfy --json env # see workspace/models path ``` ### `cloud_http_error` (HTTP 4xx/5xx from cloud) `details.status` is the HTTP code. `details.body` is the truncated server response. Most common: - `401 invalid auth token` → token audience mismatch. Decode the token at jwt.io or via `python3 -c 'import base64,json,sys; ...'` and check `aud`. The `aud` field must match what `/api/prompt` expects. - `404` returning XML `<AuthenticationRequired>` → wrong path. Real ComfyUI endpoints on cloud live under `/api/*`; everything else hits the CDN catch-all. - `503` → check the Comfy Cloud dashboard or server logs for deployment health. ### `cloud_rate_limited` (HTTP 429 from cloud) Throttling is not a verdict on the workflow, so do not edit it. Wait `details.retry_after` seconds (when present; otherwise a few seconds). A 429 does not by itself prove a submit had no effect, so before re-running `comfy run`, check `comfy jobs ls --where cloud` for the job. A 429 while `--wait` polls means the job was already submitted: follow it with `comfy jobs watch <prompt_id> --where cloud` instead of re-running. ### `cloud_payment_required` (HTTP 402, or a legacy typed 429, from cloud) The cloud refused the submit because the account's plan does not allow the run: free generations used up, a subscription required, or a partner node or model that needs a paid plan (`details.reason`, when the server sent a type). The cloud answers this with HTTP 402; older deployments sent a 429 whose body type is a plan refusal, so `details.status` is 402 or 429. Either way it is not throttling and not a problem with the workflow, and nothing was queued. Do not retry or edit the workflow: tell the user the server's message (`message`, `details.body`). ### `cloud_timeout` `cloud_timeout` — the run went **silent** for `--timeout` seconds (default 120). `comfy run --timeout` is a per-event-silence deadline on both local and cloud: it resets whenever the job reports progress, so a workflow streaming progress can run indefinitely. Wall-clock limits exist only on `comfy jobs watch --max-wait` (default 600s, cloud). Recovery: re-run with a larger `--timeout`, or submit async and `comfy jobs watch <id>`. ``` RES=$(comfy --json run --workflow X.json --where cloud) # async by default PID=$(echo "$RES" | jq -r .data.prompt_id) comfy --json-stream jobs watch "$PID" --where cloud --max-wait 1800 ``` ### `ws_timeout` / `ws_disconnected` (local) The WebSocket dropped mid-stream. Reconnect: ``` comfy jobs status <prompt_id> # one-shot snapshot comfy --json-stream jobs watch <prompt_id> # re-attach ``` The local server keeps the job; the CLI just lost its tail. ### `cql_query_invalid` `cql_query_invalid` — raised when a legacy `--query` string is passed to `comfy templates ls`. There is no query grammar; use flag-based filtering instead: `--type image|video|audio`, `--tag <t>`, `--model <m>` (templates) and `--produces/--accepts/--category/--pack` (`comfy nodes ls`). ### `cql_no_graph` The CLI needs an `object_info.json` to query against. Two options: ``` comfy launch # then re-run the nodes command comfy --json nodes ls --produces IMAGE --input /path/to/object_info.json ``` ### `internal_error` The command crashed on an exception it did not handle. This is a comfy-cli bug, not a bad input. `details.exception` names the type and `details.traceback` lists the innermost `file:line:func` frames. The full traceback is on stderr. Re-read the file or state before retrying, because the crash may have happened after a write. If the same call crashes again, take another route (e.g. `set-slot` instead of `set-widget`, or a different address form) and report the envelope as a bug. Do not retry it in a loop. ### `comfy generate` is partially machine-readable `comfy generate` is partially machine-readable: `generate <model> --json` and `generate resume <id> --json` print the raw API response as JSON; `generate upload <file> --json` emits structured `{url, expires_at, ...}`; `generate <model> --emit-workflow out.json` goes through the full renderer envelope (`command: "generate emit-workflow"`, error code `emit_workflow_failed`). The default proxy path (`generate <model>` without those flags) is still pretty-only — don't parse it. Known sharp edge: `generate resume` for BFL can raise a raw traceback on an expired/unknown id (HTTP 404 is unwrapped). ## Job-stuck triage If a prompt seems to hang: ``` # 1. Is it still tracked? comfy --json jobs ls # 2. What does the server think? comfy --json jobs status <prompt_id> # 3. Watch live events (NDJSON, one per line) comfy --json-stream jobs watch <prompt_id> ``` Three possible answers: | Symptom | Likely cause | Fix | |---|---|---| | `status: pending`, `queue_position > 0` | Earlier jobs ahead of you | Wait or cancel them | | `status: running` but no progress events | A long sampler step, or a hung custom node | Wait one sampler-step's worth; if still stuck, interrupt | | `status: error` with no `error_message` | Server crashed mid-execution | Check the Comfy Cloud dashboard or server logs (cloud), or the stdout of `comfy launch` (local) | ## Interrupting / cancelling ``` comfy --json run --workflow X.json # async by default, returns a prompt_id # later, if it's running too long: comfy jobs cancel <prompt_id> # works on both local and cloud ``` ## When `--json` makes diagnosis worse, not better Pretty mode hides the envelope behind a rendered panel. If the rendered output is opaque, **always re-run with `--json`** — that's the contract. Conversely, if `--json` floods you with NDJSON, drop `-stream` to get a single envelope. ## What to NOT do - Don't `chmod` files in the model dirs to "fix" load failures — the path is wrong, not the permissions. - Don't delete the OAuth session to "reset" — that loses state. Use `comfy cloud logout` and `comfy skills uninstall` instead. - Don't paste raw error messages into prompts without the `details` block — the details are usually what disambiguates the fix. ## Where to look when nothing in the envelope helps 1. `comfy --json env` → interpreter, workspace, server reachability, conda env 2. `comfy --json which` → resolved workspace path + how it was picked 3. `comfy --json cloud whoami` → cloud session state + base URL 4. Server logs: - Local: whatever stdout `comfy launch` was attached to (foreground), or the journal/console for `comfy launch --background` - Cloud: check the Comfy Cloud dashboard or server logs 5. The bundled `comfy` skill — re-read it; the right command for what you're trying to do is almost certainly already documented there.