Skip to content

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 ​

FieldMeaning
codeStable E_* identifier
messageHuman-readable summary
nodeIdIR node, when applicable
inputInput/param name
expected / gotTypes or values
allowedCombo options, for E_BAD_COMBO
hintActionable suggestion
nodeErrorsPer-node children (server node_errors)
detailsOriginal payload

CLI failures print JSON on stderr:

json
{ "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 ​

SymptomWhat to runLikely cause
Node class missingcwf inspect . --url URLClass not in live /object_info. comfy node install <registry-id> or recapture snapshot.
Lock driftcwf lock --url URL after reviewing diffComfy or custom nodes changed. Update snapshot + codegen on purpose.
Generated types stalecwf codegen --from object_info.json -o …You installed a pack and did not regenerate.
E_TYPE_MISMATCHcwf explain fileWrong handle. Check .MODEL vs .CLIP. Use unsafe only if the node lies.
rawNode requiredSnapshot the instance that has the classCodegen from the right environment. rawNode is the escape hatch, not the default.
E_UNBOUND_PARAMcwf inspect for required paramsPass --param or declare a default.
Path not portablecwf pack → E_PACK_LOCAL_PATHcwf expose … --required. Do not publish C:\Users\….
Runtime Comfy errorread E_NODE_EXECUTION_ERROR / nodeErrorsMissing model, OOM, node bug. Graph compiled; Comfy failed.
Package validates, model missingrequires.models is informationalPlace the checkpoint yourself. No downloader.
Pack installed, still failingready: falseRestart Comfy, then inspect --url until classes show ✓.

Branching ​

ts
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;
    }
  }
}

Released under the MIT License. Unofficial project. Not affiliated with or endorsed by Comfy Org.