July 22, 2026·9 min read·app.nz

ComfyUI lesson 10: Debug any broken ComfyUI workflow

Start at the first red node and resolve models, nodes, VRAM, shapes, and blank outputs systematically.

Listen to this article

On-device voice

Uses the voice built into your browser; no article text leaves this page.

Audio narration is not supported by this browser.

Most ComfyUI errors are literal once you read the first failing node. Do not debug the final blank preview first; find the earliest red node and inspect the terminal trace around its id and class type.

The quick-fix table

Symptom	Cause → fastest useful check
Model not found	Wrong folder or filename → match the workflow string exactly, then refresh models.
Red unknown node	Missing or incompatible custom node → use Manager’s “install missing,” inspect the repository, then restart.
CUDA out of memory	Weights and activations exceed VRAM → use batch 1, a smaller canvas, tiled VAE, quantized weights, or offload.
Tensor size mismatch	Wrong model family or image dimensions → match LoRA, ControlNet, and base architectures; use multiples of 64.
CLIP input/type error	Wrong loader or disconnected conditioning → trace CLIP → text encode → sampler.
Black or green output	VAE mismatch, precision issue, or NaNs → use the checkpoint VAE or a known fp16-fix VAE; lower CFG.
Output ignores source	Img2img denoise is too high or ControlNet is weak → lower denoise or raise control strength.
Output barely changes	Denoise is too low → sweep 0.30, 0.50, and 0.70.
Queue runs forever	Worker is downloading weights or a node is hung → read worker logs and verify model mirror/cache state.
Works locally, fails by API	UI-format JSON or an unmapped file input → export Save (API Format), then map or upload every media input.
Different result on another machine	Runtime, node, or precision drift → record versions and compare with tolerance, not only pixel identity.
Disk fills unexpectedly	Outputs, temp inputs, or model duplicates → inspect output, temp, and model folders before deleting anything.

A repair sequence worth memorizing

Reproduce once with queue size one.
Note the first failing node id and class type.
Verify its required model filenames and node version.
Reduce batch and resolution if memory is implicated.
Bypass the suspicious branch with a Preview/Save node.
Compare against the downloadable known-good workflow.
Save the repaired API graph with runtime and model provenance.

The lesson points to the small Real-ESRGAN upscale graph because it is a good diagnostic: no diffusion, one compact model, and few nodes. If that graph fails, fix the worker, file inputs, or model path before blaming sampler settings.

Bookmark this table. Better still, copy it beside your workflow manifest so the fix travels with the graph.

Run the lesson, do not just read it

Open the tested workflow in Comfy Studio
Download the exact API-format JSON
CLI: app comfy download image-upscale

The gallery records model sources, minimum VRAM, custom-node requirements, and verification state beside the graph. That is the portable unit for this series.

Series progress: lesson 10 of 10. Previous: Automate batches, prompt lists, REST, CLI, and MCP You finished the series. Keep the quick-fix table bookmarked and start adapting the workflows.

The quick-fix table

Symptom	Cause → fastest useful check
Model not found	Wrong folder or filename → match the workflow string exactly, then refresh models.
Red unknown node	Missing or incompatible custom node → use Manager’s “install missing,” inspect the repository, then restart.
CUDA out of memory	Weights and activations exceed VRAM → use batch 1, a smaller canvas, tiled VAE, quantized weights, or offload.
Tensor size mismatch	Wrong model family or image dimensions → match LoRA, ControlNet, and base architectures; use multiples of 64.
CLIP input/type error	Wrong loader or disconnected conditioning → trace CLIP → text encode → sampler.
Black or green output	VAE mismatch, precision issue, or NaNs → use the checkpoint VAE or a known fp16-fix VAE; lower CFG.
Output ignores source	Img2img denoise is too high or ControlNet is weak → lower denoise or raise control strength.
Output barely changes	Denoise is too low → sweep 0.30, 0.50, and 0.70.
Queue runs forever	Worker is downloading weights or a node is hung → read worker logs and verify model mirror/cache state.
Works locally, fails by API	UI-format JSON or an unmapped file input → export Save (API Format), then map or upload every media input.
Different result on another machine	Runtime, node, or precision drift → record versions and compare with tolerance, not only pixel identity.
Disk fills unexpectedly	Outputs, temp inputs, or model duplicates → inspect output, temp, and model folders before deleting anything.

A repair sequence worth memorizing

Reproduce once with queue size one.

Note the first failing node id and class type.

Verify its required model filenames and node version.

Reduce batch and resolution if memory is implicated.

Bypass the suspicious branch with a Preview/Save node.

Compare against the downloadable known-good workflow.

Save the repaired API graph with runtime and model provenance.

Bookmark this table. Better still, copy it beside your workflow manifest so the fix travels with the graph.

Run the lesson, do not just read it

The gallery records model sources, minimum VRAM, custom-node requirements, and verification state beside the graph. That is the portable unit for this series.

Series progress: lesson 10 of 10. Previous: Automate batches, prompt lists, REST, CLI, and MCP You finished the series. Keep the quick-fix table bookmarked and start adapting the workflows.