version: "1.0.1" 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 comes out wrong — artifacts, wrong subject/pose/composition/color, blur, a ControlNet/IPAdapter/mask/LoRA not taking, a two-stage refiner or upscale degrading the result — rather than the run failing with an error (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: 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:

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.

1. Pick a probe point roughly in the middle of the suspect chain (bisect).
2. Get an output there — target an existing output node, or add a preview tap

(table above).

1. `panel_run(to_node_id = that output node)`. Only that branch renders.
2. 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.

1. Repeat until you find the first stage whose output is bad. That node (or

its inputs/widgets) is what to fix — panel_set_widget, panel_set_node_mode, a rewire, a different model — then run-to-node there again to confirm the fix before running the full graph.

1. 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 = 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 → it's late (sampler steps/cfg, VAE,

post) — 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). Don't poll; just end the turn and read the delivered image. A preview tap with no SaveImage means "no saved output ran" — that's expected for a probe.

• Shared queue. Each run-to-node queues a real (small) job; don't stack

probes — run one, read it, then the next.

• Subgraphs. Output nodes nested inside a subgraph can't be targeted yet;

probe at the root graph (add the tap outside the subgraph, fed by an exposed output rail).

Sources

• Official: comfyui-mcp panel_run to_node_id product behavior (this repo).
• Empirical: probe-point recipes from observed wrong-render cases.