Debug a ComfyUI Workflow Systematically

A workflow that worked yesterday now throws a red box, or worse, runs happily and produces something wrong. The reflex is to install another node pack, download a different checkpoint, or start turning dials. That reflex costs hours and frequently makes the graph harder to fix, because now three things have changed and you cannot tell which one mattered.

Debugging a graph is the same discipline as debugging code: classify the failure, then reduce the system until the failure has nowhere left to hide.

Read the error before you touch anything

The error text tells you which of four distinct problems you have, and they have almost nothing in common.

A missing node type error means a custom node pack is absent, disabled, or at a different version than the workflow's author had. Nothing is wrong with your settings. Read the workflow's requirements, install the pack from a source you trust, and restart. If the pack exists but the node still will not resolve, the pack updated and renamed it — check its changelog.

A shape or type mismatch means two things are wired together that should not be, or a model expects dimensions you are not providing. SDXL and SD 1.5 conditioning are not interchangeable; nor are their VAEs. These errors name a tensor shape, and the numbers are informative: a mismatch involving 768 versus 1024 is nearly always a model-family problem.

An out-of-memory error is about your device, not your graph. Resolution, batch size, model size, and whatever else is holding VRAM all contribute. Before optimising anything, check whether a previous run is still resident or whether a browser is holding a gigabyte. Then reduce batch to 1, then resolution, then consider a lower-precision model. Note that OOM can appear at the decode stage even though sampling succeeded, because VAE decoding at high resolution has its own peak.

The fourth class — runs fine, output is wrong — is where the real time disappears. There is no error to search for. This is what the rest of the lesson is about.

Reduce before you replace

The core technique is bisection, and ComfyUI makes it cheap because you can bypass a node rather than delete it. A bypassed node passes its input through untouched and can be re-enabled instantly, so a reduction is fully reversible.

Cut the graph back to its spine: load a checkpoint, encode a positive and negative prompt, an empty latent, a sampler, a VAE decode, a save. Six nodes. Run it.

If the spine fails, the problem is your installation or your model files — nothing you removed is responsible, and you should stop debugging the workflow and start debugging the environment.

If the spine works, the problem is in what you bypassed. Re-enable one branch, run, repeat. On a forty-node graph this finds the culprit in five or six runs, which is faster than reading the graph carefully, and much faster than guessing.

Two refinements make this sharper. First, fix the seed before you start, otherwise every run differs for reasons unrelated to your change and you cannot compare anything. Second, insert a preview node at the boundary between stages. Previewing the latent before decode tells you whether a colour problem originated in sampling or in the VAE — one question answered, half the graph eliminated.

The failure modes that are not errors

Some specific patterns are worth recognising by sight, because they recur:

• Washed-out or oddly tinted colour, composition correct. VAE mismatch. Load the VAE that matches the checkpoint family, or use the checkpoint's baked-in VAE.
• Duplicated heads, limbs, or repeated architecture. You are generating far above the model's training resolution. Generate at native resolution and upscale as a separate stage.
• The prompt seems ignored. Check that the positive prompt is wired to the sampler's positive input. Swapping positive and negative produces exactly this, and it looks nothing like an error.
• Grey or black output. Usually a NaN in sampling, often from a precision setting or an incompatible LoRA. Try a different sampler first; it is a one-click test.
• A LoRA has no visible effect. Check its strength, and check that it was trained for your checkpoint's family. Cross-family LoRAs load without complaint and do nothing.

Practice: build a bug report packet

Once you have reduced the failure, you may still need help. What you send determines whether you get an answer in an hour or a week.

Send the reduced workflow, not the original. A six-node repro is something a stranger will actually open. Include the application build, every custom node pack with its version or commit, and the exact model filenames — "SDXL" is not a filename and there are dozens of variants. Add your GPU, VRAM, driver, and OS. Paste the complete console traceback, not the toast notification, which is usually truncated at the least useful point.

Then scrub it. Workflow JSON embeds absolute filesystem paths, which frequently contain your real name. Console output can contain API tokens if you have any cloud nodes installed. Check both before posting to a public issue tracker.

Common mistakes

Installing your way out. Adding node packs to fix a problem enlarges the surface area for the next problem. Most graphs fail because of a wire, a model mismatch, or a setting — not a missing feature.

Changing several things per run. If you adjust the sampler and the CFG and swap the VAE, and it works, you have learned nothing that transfers.

Trusting a downloaded workflow as a black box. Record where a workflow came from, review the node packs it demands, and keep a tested baseline you can always return to. A graph that requires an obscure pack from an unfamiliar account is asking for code execution on your machine, and that deserves a moment's thought before you click install.