List / Batch Inspector

There is a specific class of ComfyUI bug where everything is wired correctly, nothing is red, and the workflow is wrong. The node ran four times when you wanted once. Or once when you wanted four. Or saved one file out of five. The cause is almost always that you have a batch on the wire where you thought you had a list, or the other way round - and the two look identical on the canvas, because both are typed IMAGE.

This node tells you which one you are holding. Drop it on the wire, run, read kind and count. It is the debugger for the half of ComfyUI that has no error messages.

How it works

value is a * list input, so the engine hands the node the whole container rather than mapping over it. Then:

• If the container has more than one item, that is a genuine list - report list with its length.
• If it has exactly one item, look at that item. A Python list or tuple is itself a list, so report list with its length. A tensor of rank 3 or 4 - which is what IMAGE and MASK are - is a batch, so report batch with its size in dimension 0. Anything else is unknown with a count of 0.

Outputs are kind (a string: list, batch or unknown) and count (an integer). Wire them into a show-text or note node to read them on the canvas, or convert them into primitives and use them to drive logic.

The three answers and what they mean

batch means one execution carrying N images in a single tensor. Everything downstream happens at once; per-image control is impossible without splitting.

list means N values, so the node consuming it runs N times. Cost multiplies, and per-item settings become possible.

unknown means neither. That is not an error - it is what you get for structured types like SEGS, a tile layout, an accumulator, or a conditioning, because they are neither Python sequences nor rank-3/4 tensors. It is a signal that you are looking at one object with internal structure, not a stack of items, and that the right diagnostic is a type-specific node rather than this one.

Where it earns its place

Three situations, in order of how often they come up. First: after any split or merge - Image Batch To Image List, Image List To Image Batch, List Any (Append) - confirm what came out before you build four more nodes on top of the assumption. Second: in a workflow you downloaded, where you cannot see how many times a node is running and the graph is too dense to reason about statically. Third: at the end of a loop, on the accumulator's converted output, to check the count is the one you expect before a save node writes files.

It costs nothing: no tensors are read, no data is copied, no VRAM is touched. It looks at structure, not content. Leave it in the graph.

Install

Part of ComfyUI-Utility-Suite. ComfyUI Manager → search ComfyUI-Utility-Suite → install → restart, or:

cd ComfyUI/custom_nodes
git clone https://github.com/tom-m-2020/ComfyUI-Utility-Suite

Restart ComfyUI. No models, nothing to download; the pack's declared dependency is opencv-python-headless and this node does not use it. The pack is written against the newer V3 node API, so it needs a recent ComfyUI.

Traps

Read kind, not count. A batch of four and a list of four both report a count of four, by design. The number alone tells you nothing; the pair is the answer.

unknown with a count of 0 is normal for structured types. Do not treat it as a failure and do not go hunting for a bug - a SEGS is a two-tuple of canvas and entries, and this node deliberately refuses to guess what that means.

It only recognises rank-3 and rank-4 tensors. A 5-D tensor - a video latent or a video VAE output - comes back as unknown, even though it is genuinely a batched tensor. If you are working with video models, expect that and use a shape-aware node instead.

It reports, it does not fix. Nothing here converts a batch to a list or back; it tells you which one you have so you can pick the right converter. That division of labour is why it is safe to leave wired in permanently.