While Loop icon

While Loop

Control-flow node to loop until a condition is false

While Loop

AI-generated

Summary

Control workflow iteration by looping input items until a condition is false, either based on a fixed count or a custom expression. Outputs items continuing the loop separately from those that are done.

Inputs

  • Mode (required) — Select 'Counter' to loop a fixed number of times or 'Expression' to loop while a custom n8n expression returns true.
  • Max Iterations (required) — Set the maximum number of iterations to prevent infinite loops.
  • When Max Reached (required) — Choose whether to stop the loop gracefully or throw an error if the maximum iteration limit is reached.
  • Condition Expression — Define an n8n expression that must evaluate to true to continue looping. Available variables: $json.loopIteration, $json.loopFirst, $json.loopMax. Only shown when Mode is 'Expression'.
  • Add Loop Metadata — Toggle to include loop iteration metadata (loopIteration, loopFirst, loopMax) on each output item continuing the loop.

Output shape

Two outputs: 'Done' with items where the loop finished, and 'Continue' with items for the next iteration.

If using 'Expression' mode, the condition is evaluated per item with loop metadata injected. The node maintains internal loop iteration state between executions and caps iterations to Max Iterations. When Max Iterations is exceeded, behavior depends on the selected 'When Max Reached' option.

Examples

Example 1: Loop 3 times per item using Counter mode

Set Mode to 'Counter' and Max Iterations to 3. Each input item passes through the loop 3 times, emitting on 'Continue' until done then on 'Done'.

Example 2: Loop while a condition holds using Expression mode

Set Mode to 'Expression' and provide a condition expression such as '{{$json.loopIteration < 4}}' to continue looping while the iteration count is less than 4.

Links

Discussion