flowable/flowable-engine · error · FlowableIllegalArgumentException

Invalid number of instances: must be a non-negative integer

Error message

Invalid number of instances: must be a non-negative integer value, but was ${nrOfInstances}

What it means

SequentialMultiInstanceBehavior.createInstances throws this when resolveNrOfInstances returns a negative value. The number of loop instances for a sequential multi-instance activity must be zero or a positive integer; a negative count is a configuration or expression error.

Source

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

public class SequentialMultiInstanceBehavior extends MultiInstanceActivityBehavior {

    private static final long serialVersionUID = 1L;

    public SequentialMultiInstanceBehavior(Activity activity, AbstractBpmnActivityBehavior innerActivityBehavior) {
        super(activity, innerActivityBehavior);
    }

    /**
     * Handles the sequential case of spawning the instances. Will only create one instance, since at most one instance can be active.
     */
    @Override
    protected int createInstances(DelegateExecution multiInstanceRootExecution) {

        int nrOfInstances = resolveNrOfInstances(multiInstanceRootExecution);
        if (nrOfInstances == 0) {
            return nrOfInstances;
        } else if (nrOfInstances < 0) {
            throw new FlowableIllegalArgumentException("Invalid number of instances: must be a non-negative integer value" + ", but was " + nrOfInstances);
        }

        // Create child execution that will execute the inner behavior
        ExecutionEntity execution = CommandContextUtil.getExecutionEntityManager()
                .createChildExecution((ExecutionEntity) multiInstanceRootExecution);
        execution.setCurrentFlowElement(multiInstanceRootExecution.getCurrentFlowElement());

        // Set Multi-instance variables
        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_INSTANCES, nrOfInstances);
        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_COMPLETED_INSTANCES, 0);
        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_ACTIVE_INSTANCES, 1);
        logLoopDetails(multiInstanceRootExecution, "initialized", 0, 0, 1, nrOfInstances);

        executeOriginalBehavior(execution, (ExecutionEntity) multiInstanceRootExecution, 0);

        return nrOfInstances;
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the loopCardinality/collection expression and guard it against negative results before the multi-instance activity
Clamp the value in the expression, e.g. ${Math.max(0, list.size() - 5)}
Fix the upstream variable/delegate that produces the negative count
Test the expression with boundary data (empty/small collections) in a unit test of the process

Example fix

// before
loopCardinality: ${items.size() - 1}
// after
loopCardinality: ${Math.max(0, items.size() - 1)}

Defensive patterns

Strategy: validation

Validate before calling

// Guard loop cardinality before the multi-instance activity
int nr = resolveNrOfInstances(execution);
if (nr < 0) {
    throw new IllegalArgumentException("nrOfInstances must be >= 0, was " + nr);
}

Prevention

Clamp arithmetic expressions with Math.max(0, ...)
Test multi-instance expressions against empty and small collections
Avoid computing cardinality from mutable counters

When it happens

Trigger: A multi-instance activity whose loopCardinality expression or collection-based resolveNrOfInstances computes a negative integer — e.g. an expression like ${list.size() - 5} evaluated when the list has fewer than 5 elements.

Common situations: Arithmetic expressions on collection sizes or variables that can go negative; a custom CollectionExpression or bean returning a negative count; misconfigured cardinality variables polluted by earlier steps.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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