A ComfyUI workflow is easiest to debug when you can explain what each node consumes and produces. Start with a minimal graph and a model known to work with that graph before adding custom nodes, upscalers or control inputs.
This guide includes an illustrative API-prompt graph and an offline reference check. No image generation, GPU timing or VRAM comparison was performed for this article.
Follow the data through a basic graph
The official first-generation guide walks through loading a checkpoint and producing an image. In a conventional checkpoint workflow, text is encoded, a latent is sampled, the latent is decoded through a VAE and the image is saved.
The workflow JSON specification describes the saved UI graph. Do not confuse that format with an API prompt keyed by node IDs and containing class_type and inputs. An exported UI workflow should not be blindly submitted as an API prompt.
Different model families can need different loaders and encoders. A graph for a conventional checkpoint is not a universal FLUX or video workflow. Start from the official example for the exact model family.
An inspectable API-prompt example
The example API prompt contains a checkpoint loader, text encoders, an empty latent, sampler, VAE decoder and save node. The checkpoint filename is a deliberate placeholder that must be replaced with a compatible installed artifact.
The offline checker verifies basic node references and rejects a missing reference or a cycle. The execution record records those checks. It does not validate ComfyUI’s full node types, model compatibility or actual execution.
The example uses a small illustrative image size and sampler configuration to make the graph readable. Those values are not a quality recommendation or a device-performance promise. Use the matching official workflow and verify the model license before generating.
Make a result reproducible
Use the workflow run record. Save the workflow, model filenames and hashes, ComfyUI version, custom-node revisions, seed, dimensions, batch size, sampler settings and environment.
Keep output images with the record. A seed alone is insufficient when the model, node implementation, precision or execution backend changes. Record dependency changes before comparing an old image with a new one.
Change one component at a time while debugging. First confirm the base graph works. Then add one custom node or conditioning input and repeat. This makes it possible to identify the transition that caused a failure.
Troubleshoot the failing stage
| Symptom | Check first |
|---|---|
| Checkpoint absent from selector | File path, extension and whether the model directory was refreshed |
| Missing node type | Required custom-node package and its supported version |
| Shape or type mismatch | Whether the loader, encoder and model family belong together |
| Out of memory | Model representation, resolution, batch size and runtime settings |
| Output changes unexpectedly | Seed, prompt, model hash and node/runtime changes |
| API rejects the payload | API prompt format versus UI workflow JSON |
Read the failing node and error message before reinstalling everything. Preserve the minimal failing workflow. For memory errors, measure the exact configuration on the target device; do not infer capacity from a generic GPU-name table.
Custom nodes and performance claims
The custom-node installation guide warns that unverified plugins can compromise the system. A custom node executes code; a workflow file asking for a package is not sufficient reason to trust that package. Inspect the source and use a controlled environment.
To compare speed or memory, keep model, precision, resolution, batch, seed, sampler and hardware fixed. Report loading time separately from generation time, and include failed runs. The previous fixed speed and VRAM advantages over other interfaces were not supported by a reproducible benchmark and are no longer asserted.
Revision note
Updated October 20, 2026. Removed unsupported speed/VRAM comparisons and impossible blanket hardware recommendations. Added a format distinction, inspectable example graph, real structural checks and a reproducibility record.
Primary sources
Checked October 20, 2026: comfy workflow; comfy schema; comfy security.