/debug-render

name: debug-render
description: Debug a WRONG or imperfect render (not a hard error) by inspecting inputs and intermediate steps with run-to-node. Render one branch up to an output, preview-tap latents/masks/preprocessor maps, localize the first bad stage, then fix. Use when a final image/video completes but looks wrong, such as artifacts, wrong subject/pose/composition/color, blur, a ControlNet/IPAdapter/mask/LoRA not taking, or a two-stage refiner or upscale degrading the result. For errors/OOM/missing nodes use the troubleshooting skill.

Debugging renders with run-to-node

When a final asset looks wrong (not when it errors), don't re-roll the whole graph and hope. Localize the fault. Render only as far as one stage and look at what that stage actually produces. The wrong-looking output is downstream of a *first* bad step. Find that step, fix it there, and everything after it follows.

The tool for this is `panel_run` with `to_node_id` ("run to node"), which uses ComfyUI's native partial execution. Only the target output node plus everything upstream of it renders; every other branch is skipped. That makes each probe fast and cheap, and the output is delivered to you automatically, same as any run. Don't poll.

When to reach for this

• A final image/video is wrong: artifacts, wrong subject/pose/composition, off

color, soft/blurry, melted hands, wrong style.

• A conditioner isn't "taking" (ControlNet, IPAdapter, a mask, an inpaint, a

LoRA) and you can't tell if the *input* to it is wrong or the *node* is wrong.

• A multi-stage pipeline (base → refiner, txt2img → upscale, decode → post)

degrades, and you need to see which stage introduces the problem.

• You only want to test one branch of a multi-output graph without paying for

the others.

If instead the run fails (red error, OOM, missing node, black image from a crash), use the troubleshooting skill. This skill is for outputs that *complete* but look wrong.

The one hard rule: `to_node_id` must be an OUTPUT node

ComfyUI can only run *to* an output node: SaveImage, PreviewImage, SaveVideo, SaveAudio, etc. (these show `is_output: true` in `panel_query_graph` detail rows). A bare KSampler / VAEDecode / preprocessor is not an output node, so you can't target it directly. To inspect a point that isn't already an output, add a preview tap there:

| You want to see… | Wire type | Tap to add | Wiring | |---|---|---|---| | An intermediate image (post-process, refiner stage, composite) | IMAGE | `PreviewImage` | image → `PreviewImage.images` | | A latent (after a sampler, before/after upscale) | LATENT | `VAEDecode` → `PreviewImage` | latent → `VAEDecode.samples`; reuse the graph's VAE → `VAEDecode.vae`; then → `PreviewImage` | | A mask (inpaint, segmentation, attention) | MASK | `MaskToImage` → `PreviewImage` | mask → `MaskToImage.mask` → `PreviewImage` | | A ControlNet/preprocessor map (depth/pose/canny) | usually IMAGE already | `PreviewImage` | the preprocessor's IMAGE output → `PreviewImage.images` | | The actual prompt/conditioning | CONDITIONING | (can't preview as an image) | inspect widget values / the text node feeding it instead |

Build a tap with `panel_add_node` + `panel_connect`, run to it, inspect, then `panel_remove_node` the tap when you're done (unless the user wants to keep it).

The loop

1. **Read the graph.** `panel_graph_outline` (then `panel_query_graph` for specifics). Note node ids, the output nodes (`is_output: true`), and every node's mode. A node in `bypass`/`mute` on the path is OFF and is a top cause of wrong renders. Fix modes first with `panel_set_node_mode` before you blame anything else. 2. **Pick a probe point** roughly in the middle of the suspect chain (bisect). 3. **Get an output there.** Target an existing output node, or add a preview tap (table above). 4. **`panel_run(to_node_id = that output node)`.** Only that branch renders. 5. **Look at what's delivered.** Is *this* stage already wrong, or still fine?

• Still fine: move the probe downstream; the fault is later.
• Already wrong: move the probe upstream; the fault is earlier.

6. Repeat until you find the first stage whose output is bad. That node (or its inputs/widgets) is what to fix, via `panel_set_widget`, `panel_set_node_mode`, a rewire, or a different model. Then run-to-node there again to confirm the fix before running the full graph. 7. **Clean up** temporary preview taps (`panel_remove_node`) and do a final full `panel_run` to produce the real saved asset.

Symptom → where to probe first

• **Whole image wrong subject/style.** Preview the conditioning's source (the

text/prompt node, the sampler's positive input via a decode of its latent).

• **ControlNet ignored / wrong structure.** Preview the preprocessor map

(the depth/pose/canny IMAGE going into the ControlNet). A blank or wrong map means the problem is the preprocessor or its input, not the sampler.

• **IPAdapter/reference not taking.** Preview the reference image after any

resize/crop the IPAdapter chain applies.

• **Inpaint/outpaint bleeding.** `MaskToImage`-preview the mask actually reaching

the sampler (mask misalignment is the usual culprit).

• **Refiner/upscale degrades it.** Preview the base latent (VAEDecode tap)

*before* the refiner vs after. If the base is good and the result is bad, the refiner/upscale stage is at fault.

• **Right content, bad quality only.** The fault is late (sampler steps/cfg, VAE,

post), so probe near the end first.

Gotchas

• **Output-node only.** If you target a non-output node, the run is rejected with

a message saying so. Add a preview tap instead.

• **Modes matter.** A bypassed/muted node on the probed path silently changes what

renders. Check modes in step 1.

• **Auto-delivery.** The probe's output node fires an `executed` event and the

image is delivered to you inline, including PreviewImage taps, which arrive labeled as a *preview* (temporary, not a saved file