flowable/flowable-engine · error · FlowableIllegalArgumentException

Couldn't resolve collection expression nor variable referenc

Error message

Couldn't resolve collection expression nor variable reference

What it means

Thrown by MultiInstanceActivityBehavior.resolveNrOfInstances when a multi-instance activity is configured to use a collection (loopCardinality absent) but neither the collectionExpression nor the collectionVariable (nor a collection handler) could be resolved to an actual collection. usesCollection() was true, yet resolveAndValidateCollection found no usable source for the instances.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/MultiInstanceActivityBehavior.java:459

        return FlowableEventBuilder.createMultiInstanceActivityCompletedEvent(eventType,
                getLoopVariable(execution, NUMBER_OF_INSTANCES),
                getLoopVariable(execution, NUMBER_OF_ACTIVE_INSTANCES),
                getLoopVariable(execution, NUMBER_OF_COMPLETED_INSTANCES),
                flowNode.getId(),
                flowNode.getName(), execution.getId(), execution.getProcessInstanceId(), execution.getProcessDefinitionId(), flowNode);
    }

    @SuppressWarnings("rawtypes")
    protected int resolveNrOfInstances(DelegateExecution execution) {
        if (loopCardinalityExpression != null) {
            return resolveLoopCardinality(execution);

        } else if (usesCollection()) {
            Collection collection = resolveAndValidateCollection(execution);
            return collection.size();

        } else {
            throw new FlowableIllegalArgumentException("Couldn't resolve collection expression nor variable reference");
        }
    }

    @SuppressWarnings("rawtypes")
    protected void executeOriginalBehavior(DelegateExecution execution, ExecutionEntity multiInstanceRootExecution, int loopCounter) {
        if (usesCollection() && collectionElementVariable != null) {
            Collection collection = resolveAndValidateCollection(execution);

            Object value = null;
            int index = 0;
            Iterator it = collection.iterator();
            while (index <= loopCounter) {
                value = it.next();
                index++;
            }
            setLoopVariable(execution, collectionElementVariable, value);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure the referenced collection variable exists as a Collection/Iterable before the multi-instance activity executes.
Fix typos in the collection attribute value or expression.
Set the collection explicitly in a preceding service task or at process start: execution.setVariable("assigneeList", list).
Alternatively use loopCardinality instead of a collection if you only need a fixed instance count.
Validate the BPMN XML: the collection attribute must be flowable:collection on multiInstanceLoopCharacteristics and parsed by the deployment.

Example fix

// before: variable never set, process starts the multi-instance task
// after: initialize the collection before the multi-instance activity
<serviceTask id="initList" flowable:expression="${'a,b,c'.split(',')}">
  <extensionElements>
    <flowable:out source="x" target="assigneeList"/>
  </extensionElements>
</serviceTask>

Defensive patterns

Strategy: validation

Validate before calling

if (execution.getVariable("assigneeList") == null) {
    throw new IllegalStateException("Collection variable 'assigneeList' must be set before the multi-instance activity");
}

Try / catch

try {
    return task.execute(execution);
} catch (FlowableIllegalArgumentException ex) {
    if (ex.getMessage().contains("Couldn't resolve collection")) {
        logger.error("Multi-instance collection not configured/resolvable: {}", ex.getMessage());
    }
    throw ex;
}

Prevention

Always initialize collection variables at process start or in a preceding service task.
Keep flowable:collection attribute values in sync with actual variable names (shared constant).
Prefer loopCardinality when a fixed count suffices.
Validate BPMN models on deployment with a linter that checks collection references.

When it happens

Trigger: A <multiInstanceLoopCharacteristics> with an activiti:collection / flowable:collection attribute whose value is neither a valid variable name present in the execution nor a resolvable expression, so resolveAndValidateCollection falls through without returning a Collection and resolveNrOfInstances hits the else branch.

Common situations: Collection attribute pointing at a process variable that was never set; expression typo (e.g. ${itemListt}); collection defined on the wrong scope so the variable is invisible to the sub-execution; XML attribute name misspelled so it is never parsed into collectionVariable/collectionExpression.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/da2dfff7d2957cdd. Report an issue: GitHub.