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 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:

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