Loop

Marks the top of a loop region. Everything between it and its paired Loop End repeats.

Purpose

Repeats a block of nodes — a fixed number of times, while a condition stays true, or until a condition becomes true. Use it to grind a task N times, keep trying until something appears, or process a list.

You draw a plain chain of body nodes. The enter, repeat and exit wiring is generated for you — there is no back-edge to draw and no loop ports on the canvas.

When to use it

• Repeating a task a known number of times.
• Continuing while a resource lasts (While).
• Retrying until a state is reached (Until).
• Iterating with a counter variable.

When not to use it

• For a simple "do this until the quota is met" where a Variable counter plus an If is clearer and survives branching better.
• To retry one flaky node — use that node's retry policy.
• To poll for something to appear — a Find Image with a longer timeout already polls.

Requirements

• A paired Loop End. The region is validated at Save.
• A Max iterations value.
• For While/Until, a boolean condition.
• A counter variable, if used, must be pre-declared and numeric.

How it runs

Every mode also stops at Max iterations. A While condition that never flips still terminates.

Settings

Setting	Type	Range	Notes
Mode	choice	count, while, until	Required
Max iterations	integer	1–1000	Required. A safety cap enforced in every mode. Accepts a {{variable}}
Condition	expression	≤ 1000 chars	Required for While/Until; must be boolean
Counter variable	variable path	—	Optional; receives the pass index, starting at 0

While versus Until

• While repeats while the condition is true — it stops when the condition becomes false.
• Until repeats until the condition is true — it stops when the condition becomes true.

They are opposites. Picking the wrong one produces a loop that either runs once or runs to the cap.

Max iterations accepts a variable

maxIterations can be a whole-string {{variable}} reference, so the repeat count can be supplied per run as a Flow Input:

Max iterations: {{items_per_trip}}

This is how one saved flow handles "process 3 items" and "process 10 items" without editing.

Loop End can aggregate

The paired Loop End can optionally collect a body node's output across iterations and expose it on the loop's exit. Modes include last, first, collectAll, unique, successOnly, failureOnly, successCount, failureCount, and iterationCount.

iterationCount is the simplest and most commonly useful — "how many passes actually ran".

Ports

Loop is a region marker, not a branch node. You wire a plain success chain from it into the body; the repeat and exit routing is generated at compile time.

Port	Notes
Success	Wires to the first body node. Required
Fatal	Invalid mode, cap, or a non-boolean condition. Never followed

Use Break to leave early and Continue to skip to the next pass.

Basic example

Repeat a collect step ten times:

• Mode: Count
• Max iterations: 10

Realistic example — a bounded, variable-length loop

Two termination conditions, both safe: the loop stops at the caller-supplied count, or early via Break when there is nothing left to process.

Advanced example — bounded retry with a flag

Loop as a retry region, using a flag variable to record success:

This is the shape to reach for when you need to retry a group of nodes — node-level retry only covers a single node.

Best practices

• Set Max iterations to a real bound, not the maximum. It is your protection against an infinite loop.
• Update whatever your While/Until condition tests inside the body, or you will always hit the cap.
• Use Break for "nothing left to do" rather than letting the loop spin.
• Declare the counter variable first, as a number.
• Bind Max iterations to a Flow Input to make the flow reusable.
• Watch maxNodeExecutions. A 200-iteration loop over 12 nodes is 2400 executions — raise the flow's guardrail to match.

Performance notes

• Loop itself costs nothing; the body's cost multiplied by iterations is what matters.
• A Wait inside a loop is the most common performance mistake: 1500 ms × 200 iterations is five minutes of idling.
• Detection nodes inside a loop dominate cost. Give them tight search regions.
• Aggregation modes that collect data (collectAll, unique) retain per-iteration values; prefer counts when you only need a number.

Memory notes

• Every iteration records node results into the run context, so a long loop grows nodeResults steadily.
• collectAll aggregation retains one entry per iteration — bounded by Max iterations, but real memory for a 1000-iteration loop.
• For very long-running work, prefer repeated scheduled runs over one enormous loop.

Common mistakes

Mistake	What happens	Fix
While condition never updated	Loops to the cap every time	Update the tested variable inside the body
While and Until confused	Runs once, or runs to the cap	While = while true; Until = until true
Counter not declared	Loop faults	Declare it as a number first
Missing Loop End	Validation error at Save	Every Loop needs its pair
Cap left at 1000 "just in case"	Hides real bugs, burns executions	Set a realistic bound
Loop body exceeds maxNodeExecutions	Run dies mid-loop	Raise the flow guardrail

Troubleshooting

The loop runs exactly once. An Until condition that is already true, or a While condition that is already false.

The loop always runs to Max iterations. The condition never changes — nothing in the body updates the variable it tests.

The run dies with MAX_NODE_EXECUTIONS_EXCEEDED. Iterations × body size exceeded the flow's cap. Raise it in flow settings.

Break does not leave the loop. Break belongs to the innermost enclosing loop. Check which region it sits in.

FAQ

What is the maximum iteration count? 1000.

Can the count come from a variable? Yes — maxIterations accepts a whole-string {{variable}}.

Do I draw the back-edge? No. Wire a plain chain from Loop to Loop End; the routing is generated.

Can I nest loops? Yes. Break and Continue apply to the innermost enclosing loop.

Related nodes

• Break — leave the loop early
• Continue — skip to the next pass
• Variable — counters and flags
• If — the condition inside the body
• Sub Flow — a cleaner alternative to a huge loop body

Related pages

• Execution Model — maxNodeExecutions
• Variables and Memory