Loop
FastGPT Loop node overview and usage (applicable to version 4.15.0 and above)
Node Overview
The Loop Node allows you to repeatedly execute a sub-workflow. Whether you want to process a batch of data item by item (Array Loop), or iteratively optimize a task until it meets a specific standard (Conditional Loop), the Loop Node makes it easy.

Ideal for scenarios such as:
- Summarizing paragraph chunks of a long article one by one (Array Loop)
- Refining an AI draft and repeatedly revising it if the score is below 80, until it passes (Conditional Loop)
- Calling external APIs sequentially in batches
Core Features & Loop Modes
The Loop Node provides two running modes.
1. Array Loop
- How it works: Iterates through a provided array (e.g., article paragraphs), processing one element per iteration.
- Data Injection: During each iteration, the Loop Start node automatically outputs
Current ItemandCurrent Index(0-based).
2. Conditional Loop
- How it works: Runs repeatedly based on conditions instead of an array, until a Loop Break node is executed.
- Requirement: Must contain at least one Loop Break node inside the loop container, otherwise saving or running the workflow will result in an error.
- Data Injection: During each iteration, the Loop Start node automatically outputs
Current Loop Count(1-based).
3. Error Handling & User Interaction
- Preserving Prior Run Logs: If a loop fails at some point, the logs and results from previous successful iterations are kept. You can inspect the step-by-step trace in "Run Details" to easily spot what went wrong.
- User Interaction Support: Supports nodes that require user input (like Form input) inside the loop. The loop will temporarily pause when reaching these nodes and automatically resume running from where it paused once the user completes the input.
Parameter Descriptions
Inputs
| Parameter | Required | Default | Description |
|---|---|---|---|
| Loop Type | Yes | Array Loop | Choose between Array Loop (array) or Conditional Loop (conditional). |
| Array | Yes | - | (Visible only in Array Loop mode) The list of data to process. Typically referenced from a preceding node's array output. |
| Loop Body | Yes | - | The sub-workflow to execute inside the container, starting from the Loop Start node (can be exited via the Loop Break node). |
Outputs
| Parameter | Type | Description |
|---|---|---|
| Error Text | string | The error message if the loop terminates abnormally due to an error. |
| Custom Outputs | Any | Users can add custom outputs by typing a variable name in the node's Output area and binding it to an internal node's variable reference. When the node finishes running, it outputs the values from the final iteration (or upon termination). |
Important Caveats & Best Practices
- No Nesting
- You cannot place another Loop Node or Parallel Run node inside a Loop Node.
- Returns the Final Iteration Only
- The custom outputs on the Loop Node only hold the values from the last iteration when the loop exits (it no longer aggregates all outputs into a single array).
- How to aggregate results from all iterations?
To collect data from every iteration into a list, declare an array global variable outside the Loop Node and update it inside the loop body based on the element type:- String array: In the Variable Update node inside the loop body, select the array global variable, switch the value mode to Manual Input, choose Append, and type
/in the input box to insert the current iteration's result (Variable Citation mode replaces the entire array with the referenced array). - Object array: The append box for an object array accepts JSON text. To append a dynamic object output by an upstream node, add a Code Run node inside the loop body that combines the existing global array and the current object into a new array, then update the global array variable in the Variable Update node using Variable Citation.
- String array: In the Variable Update node inside the loop body, select the array global variable, switch the value mode to Manual Input, choose Append, and type
- Variable and External Output Writeback
- After each successful iteration, global variable changes made inside the loop body are written back to the main flow. If a Variable Update node changes an output on a node outside the loop container, that output is also written back after that iteration succeeds.
- Failed iterations do not commit variable or external output changes from that iteration. When an interactive node pauses execution, the completed changes before the pause are kept as a resumable checkpoint so the loop can continue after the user submits input.
- Prevent Infinite Loops
- For Conditional Loops, ensure that a Loop Break node is reachable under certain conditions.
- The system enforces a maximum iteration limit (default 100). The loop will automatically terminate and throw an error if this limit is reached.
Deployment Settings
For self-hosted developers or operators, you can adjust the execution limits of the Loop Node via the following environment variable:
| Environment Variable | Default | Description |
|---|---|---|
WORKFLOW_MAX_LOOP_TIMES | 100 | The maximum length of input arrays and the maximum iteration limit for Conditional Loops (shared by Loop Node, Parallel Run, and the deprecated Batch Run). |
Example Scenario: Array Loop Validation and Conditional Loop Extension
Validate the data flow with an array loop before extending it to AI rewriting. The verified configuration below uses a global array captureItems = ["alpha", "beta"], replies with each item, and records the final item.

Implementation Steps
- Add an array variable
captureItemsin system configuration and enter["alpha", "beta"]. - Select Array Loop and reference
captureItemsas the input array. - Connect Loop Start to Assigned Reply inside the loop. Reference the current item as the reply content.
- Add a custom output
lastItemand reference the current item from Loop Start. Its final value isbeta. - To extend this to AI rewriting, select Conditional Loop and connect rewriting, scoring, and condition nodes inside the body. The passing branch outputs the text and reaches Loop Break; the other branch continues the next iteration. Store text and scores needed across iterations in variables.
Execution Flow & Details
This screenshot records two successful iterations of the array validation example. Expand the loop in Complete Response to inspect the iteration count, history, and per-iteration custom outputs:

- The first current item is
alpha; Assigned Reply outputsalpha. - The second current item is
beta; Assigned Reply outputsbeta. - The loop finishes with
lastItem = "beta". AI scoring in a conditional loop depends on the model and prompt; test its passing and termination paths separately.
Last updated