Debug Render

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.
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 — 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.
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 = 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).