菜单
Debugging skill for the comfy CLI — failed workflows, stuck jobs, error envelopes, and the fastest path from "it broke" to "fixed".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Generate images, videos, audio, and 3D via ComfyUI — CLI surface, workflow creation hierarchy (template → fragment → raw JSON), domain gotchas, cloud auth, multi-stage orchestration.
Use when asked to make a narrative video — an ad, brand film, short, trailer, music video, or any multi-shot clip that tells a story (not a single shot or loop). Also use when a video was rejected for "no story", "doesn't flow", "feels like a montage", or characters that change between shots.
Compose large Comfy workflows from small reusable fragment pieces — each a self-contained workflow JSON with declared inputs, outputs, and parameters. Use when iterating on complex workflows, when patterns repeat, or when a workflow JSON grows past ~200 lines.
How to present and interact during comfy creative work (images, video, audio) — show visual previews in chat, not text about files. Creative media work is iterative and visual; it is NOT like code. Use whenever generating, reviewing, or iterating on media with the comfy CLI.
| name | comfy-debug |
| description | Debugging skill for the comfy CLI — failed workflows, stuck jobs, error envelopes, and the fastest path from "it broke" to "fixed". |
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.
Every command emits the standard JSON envelope (see core skill). When error is present, map error.code to a fix below.
Three rules:
error.code to a fix below. Most codes have a one-line resolution.hint is authoritative. If it says "run: comfy launch", that's the fix. Don't paraphrase, don't guess.details carries the why. Look here before scrolling logs.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 OAuth-first: a live comfy cloud login session outranks COMFY_CLOUD_API_KEY env, which outranks a stored key. comfy cloud whoami shows which credential is active. If a stale session is causing 401s, comfy cloud logout && comfy cloud login — setting an API key will NOT override a live session.
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_formatUI-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), run comfy nodes refresh --where cloud or start a local server.
workflow_invalid_jsonThe 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, 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_timeoutcloud_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_invalidcql_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_graphThe 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
comfy generate is partially machine-readablecomfy 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).
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) |
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
--json makes diagnosis worse, not betterPretty 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.
chmod files in the model dirs to "fix" load failures — the path is wrong, not the permissions.comfy cloud logout and comfy skills uninstall instead.details block — the details are usually what disambiguates the fix.comfy --json env → interpreter, workspace, server reachability, conda envcomfy --json which → resolved workspace path + how it was pickedcomfy --json cloud whoami → cloud session state + base URLcomfy launch was attached to (foreground), or the journal/console for comfy launch --backgroundcomfy skill — re-read it; the right command for what you're trying to do is almost certainly already documented there.