Skip to main content

Flow Loops and Collection Variables: Avoiding the Single-Variable Trap

One of the most common mistakes when building Salesforce Flows with loops is using a single record variable to accumulate results. Each iteration of the loop overwrites the previous value, and when the loop exits, only the last record survives. This issue trips up both new and experienced Flow builders because Flow Builder provides no warning that data is being lost.

The Wrong Approach: Single Record Variable​

Consider a scenario where you need to loop through a collection of Order Items and build a set of records to update. A typical mistake looks like this:

Flow structure (incorrect):

  1. Get Records: Query all OrderItem records for a given Order.
  2. Loop: Iterate over the OrderItem collection.
  3. Assignment (inside loop): Set singleOrderItemVar.Status__c = "Processed" and set singleOrderItemVar.Id = {!Loop_Variable.Id}.
  4. Update Records (after loop): Update singleOrderItemVar.

The problem: singleOrderItemVar is a single record variable. Each time the loop iterates, the Assignment element overwrites the variable with the current iteration's data. After 50 iterations, singleOrderItemVar contains only the 50th record. The Update Records element modifies one record instead of fifty.

The Correct Approach: Collection Variable with Add​

The fix requires two changes: use a collection variable to accumulate records, and use the Add operator in the Assignment element to append each record to the collection.

Flow structure (correct):

  1. Get Records: Query all OrderItem records for a given Order.
  2. Loop: Iterate over the OrderItem collection. The loop variable is currentItem.
  3. Assignment (inside loop):
    • Set a single record variable's fields: tempRecord.Id = {!currentItem.Id}, tempRecord.Status__c = "Processed".
    • Add tempRecord to orderItemsToUpdate (a collection variable of type OrderItem).
  4. Update Records (after loop): Update the orderItemsToUpdate collection.

Configuring the Assignment Element​

In Flow Builder, the Assignment element configuration for the "Add" step looks like this:

VariableOperatorValue
{!orderItemsToUpdate}Add{!tempRecord}

The Add operator is the key difference. Instead of replacing the collection's contents, it appends the current record to the end of the collection. After 50 iterations, the collection contains all 50 records.

Creating the Collection Variable​

When creating the variable in Flow Builder:

  • Data Type: Record
  • Object: OrderItem (or whichever SObject you are working with)
  • Allow multiple values (collection): Checked

This checkbox is easy to miss. If it is not checked, the variable behaves as a single record and the Add operator is not available.

Why Flow Builder Does Not Warn You​

Flow Builder does not perform data flow analysis across loop iterations. It validates that the Assignment element's variable types match and that the syntax is correct, but it has no concept of "this variable is being overwritten on each iteration." The logic error is entirely on the builder to recognize.

This is a meaningful gap in the tooling. Other development environments would flag an unused variable assignment inside a loop, but Flow Builder treats each Assignment as an independent, valid operation.

Verifying Your Collection​

Before the Update Records element, add a verification step to confirm the collection contains the expected number of records:

Option 1: Decision Element

  • Create a formula: {!orderItemsToUpdate.Size} (note: Flow does not natively support .Size; use a formula resource with the ISNULL function or a count variable incremented inside the loop).

Option 2: Counter Variable

  • Add a Number variable counter initialized to 0.
  • Inside the loop, add an Assignment: counter = {!counter} + 1.
  • After the loop, display counter on a Debug Screen to confirm it matches the expected record count.

Option 3: Debug Log

  • Use a Screen element (in development) to display the collection count before the DML operation.

Key Takeaway​

Whenever you build a Flow loop that needs to accumulate records for a bulk DML operation, always use a collection variable with the Add operator. The single-variable approach silently discards all but the last record, and Flow Builder will not alert you to the problem. Building the habit of always pairing loops with collection variables eliminates an entire category of Flow bugs.