Stateful Loop
Iterate over data while preserving state. Optional delay, merge, infinite loop detection, and smart error reporting.
Overview
This node performs a stateful loop over input data, iterating through specified paths or expressions while preserving state variables across iterations. It supports optional delays between iterations, merging of results into a single output, detection of infinite or runaway loops, and configurable error handling per iteration. This node is useful for scenarios where repeated processing of data with state tracking is needed, such as polling APIs, processing batches with stateful context, or iterative data transformations.
Use Case Examples
- Iterate over an array of items, extracting a specific field from each, with a delay between each iteration to avoid rate limits.
- Perform a loop that merges all results into a single output item for easier downstream processing.
- Detect and abort or alert on infinite loops by monitoring repeated identical results.
- Initialize and update state variables in JSON format to maintain context across iterations.
Properties
| Name | Meaning |
|---|---|
| Iterate Over (Expression) | Expression or path to iterate over for each input item. |
| Output Field Path | Dot-path to extract from each iteration result; if blank, the full object is returned. |
| Delay (ms) | Pause duration in milliseconds after each iteration; can be an expression. |
| Merge Results | If enabled, merges all iteration results into a single output item with a 'merged' array. |
| Max Repeats Before Abort | Number of times the same result can repeat consecutively before aborting to prevent runaway loops. |
| Enable Loop Detection Alert Instead of Abort | If enabled, emits an alert item instead of throwing an error when a runaway loop is detected. |
| On Iteration Error | Defines behavior when an iteration throws an error: continue with logging or abort the loop. |
| Variable Initializer (JSON) | JSON string to initialize state variables accessible during iterations. |
| Max Iterations | Maximum number of iterations to perform before stopping the loop. |
Output
JSON
iteration- Current iteration number.result- Result of the current iteration, either full object or extracted field.vars- Snapshot of state variables at the current iteration.merged- Array of all iteration results if merging is enabled.alert- Boolean flag indicating an alert item (e.g., runaway loop detection).type- Type of alert or special message.message- Descriptive message for errors or alerts.
Troubleshooting
- Invalid JSON in 'Variable Initializer' will cause the node to throw an error; ensure valid JSON format.
- Runaway loop detection triggers if the same result repeats consecutively beyond the configured threshold; configure 'Max Repeats Before Abort' and 'Enable Loop Detection Alert Instead of Abort' accordingly.
- Errors during iteration can either abort the loop or be logged and skipped based on 'On Iteration Error' setting.
- Delays configured with expressions should be valid numbers to avoid unexpected behavior.