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). Don't poll; just end the
  turn and read the delivered image. A preview tap with no SaveImage means "no
  saved output ran", which is 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.