Errors and debugging

Every SDK failure carries a stable code plus structured fields. Agents branch on code, not on prose. Canonical definition: src/errors.ts. New codes may be added; existing ones do not change meaning.

Full table: Error codes.

ComfyError

Field	Meaning
code	Stable E_* identifier
message	Human-readable summary
nodeId	IR node, when applicable
input	Input/param name
expected / got	Types or values
allowed	Combo options, for E_BAD_COMBO
hint	Actionable suggestion
nodeErrors	Per-node children (server node_errors)
details	Original payload

CLI failures print JSON on stderr:

{ "error": { "code": "E_TYPE_MISMATCH", "nodeId": "n5", "input": "clip", "expected": "CLIP", "got": "MODEL" } }

Envelope warnings (not compiler codes): E_LOCK_DRIFT, E_LIVE_DEFS_UNAVAILABLE. Crashes outside ComfyError become E_UNCAUGHT.

Troubleshooting

Symptom	What to run	Likely cause
Node class missing	cwf inspect . --url URL	Class not in live /object_info. Install pack or recapture snapshot.
Custom pack unknown	cwf resolve-nodes . --url URL	No verified Registry owner. Manual cwf node-pack add, or the class is actually core.
Lock drift	cwf lock --url URL after reviewing diff	Comfy or custom nodes changed. Update snapshot + codegen on purpose.
Generated types stale	cwf codegen --from object_info.json -o …	You installed a pack and did not regenerate.
E_TYPE_MISMATCH	cwf explain file	Wrong handle. Check .MODEL vs .CLIP. Use unsafe only if the node lies.
rawNode required	Snapshot the instance that has the class	Codegen from the right environment. rawNode is the escape hatch, not the default.
E_UNBOUND_PARAM	cwf inspect for required params	Pass --param or declare a default.
Path not portable	cwf pack → E_PACK_LOCAL_PATH	cwf expose … --required. Do not publish C:\Users\….
Runtime Comfy error	read E_NODE_EXECUTION_ERROR / nodeErrors	Missing model, OOM, node bug. Graph compiled; Comfy failed.
Package validates, model missing	requires.models is informational	Place the checkpoint yourself. No downloader.
Pack installed, still failing	ready: false, restartRequired	Restart Comfy, then inspect --url until classes show ✓.

Branching

import { ComfyError } from "@stepupgaming/comfy-workflows";

try {
  await client.run({ kind: "graph", graph });
} catch (e) {
  if (e instanceof ComfyError) {
    switch (e.code) {
      case "E_BAD_COMBO":
        break;
      case "E_NODE_EXECUTION_ERROR":
        break;
    }
  }
}