🌊 Merge flow (bottleneck)

FlowNodes' "flow" system is a way to force ComfyUI to run nodes in an order the data wires don't imply (see the Flow start node for the concept). "🌊 Merge flow (bottleneck)" is the node that makes flows useful - it's the funnel every ordered sequence is supposed to pass through, and it's the piece that makes loops possible.

Its job is simple: pass an input through untouched, while claiming a Flow dependency so ComfyUI schedules things in a guaranteed sequence. Look at the code - it returns Input, Flow with no transformation. The Input socket is * (anything in, same thing out as Output), and the Flow socket is optional, so you can use it purely as a pass-through if you like. The node's two outputs are Output (the untouched value) and Flow.

The two things it's actually for

1. Sealing an order. Function nodes like 📖 Generic operation (write) mutate objects in place, and in-place mutation only works if the mutations happen in a known order. The README's advice is explicit: use flow, and "merge flow after the last operation." So the pattern is: flow start → write nodes sharing the flow line → flow merge at the end. The merge is the bottleneck that makes everything before it finish before anything after it starts.

2. Building loops. This is the headline feature and the reason for the name. Feed a flow into a repeater node (the README's example is pythongosssss's ComfyUI-Custom-Scripts repeater), and the flow - and therefore everything upstream of the merge - executes again. The merge "repeats if the flow is repeated." A counter that ticks up once per run, a loop that accumulates values into a list - those are built on exactly this. The merge's Flow output is what you route back around for the next iteration.

What beginners get wrong

• Thinking the merge changes the data. It doesn't. Input goes in, Output comes out identical. If your value is wrong after the merge, the bug is upstream of it, not in it.
• Looping without a merge. A bare flow into a repeater gives ComfyUI nothing to hold onto; the merge is what anchors the iteration boundary. No merge, no sane loop.
• Forgetting the merge exists and hand-wiring every sequence. It's tempting to just chain flow wires and skip the bottleneck. That works for a straight line, but the moment you want to repeat or branch the order, you need the merge to recombine paths.

Install

Part of the FlowNodes pack:

cd ComfyUI/custom_nodes
git clone https://github.com/gitmylo/FlowNodes
# restart ComfyUI

or ComfyUI Manager → search FlowNodes → install. No Python dependencies, no model downloads.

Troubleshooting

• Order still wrong downstream - the downstream node must actually take the Flow output. Stock ComfyUI nodes have no FLOW socket, so this pattern only reaches FlowNodes' own function nodes (and anything else that declares a FLOW input).
• Loop doesn't repeat - confirm the flow is passing through the merge, and that the repeater is wired to the merge's Flow output, per the README's "repeat if the flow is repeated" note.
• Value arrives mutated when you expected a copy - it's the same Python object. If a write node changed it, every reader sees the change. Use that to your advantage or create a fresh container.