git:20260819.9fe9ea3 to git:20260825.cab59a6

44 added, 44 removed. Audit A to A.

---

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

+ 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

+ 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.

+ *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

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

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

+ 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

+ 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,

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

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

|---|---|---|---|

| A latent (after a sampler, before/after upscale) | LATENT | `VAEDecode` → `PreviewImage` | latent → `VAEDecode.samples`; reuse the graph's VAE → `VAEDecode.vae`; then → `PreviewImage` |

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

+ 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

+ 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.

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

+ - **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 =

+ - **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

+ - **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

+ - **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 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.

+ - **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.

+ 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

+ 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

+ 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.