{"record":{"id":"494f05f45351bfe8","repo":"flowable/flowable-engine","slug":"invalid-number-of-instances-must-be-a-non-negativ","errorCode":null,"errorMessage":"Invalid number of instances: must be a non-negative integer value, but was ${nrOfInstances}","messagePattern":"Invalid number of instances: must be a non-negative integer value, but was (.+?)","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/SequentialMultiInstanceBehavior.java","lineNumber":50,"sourceCode":"public class SequentialMultiInstanceBehavior extends MultiInstanceActivityBehavior {\n\n    private static final long serialVersionUID = 1L;\n\n    public SequentialMultiInstanceBehavior(Activity activity, AbstractBpmnActivityBehavior innerActivityBehavior) {\n        super(activity, innerActivityBehavior);\n    }\n\n    /**\n     * Handles the sequential case of spawning the instances. Will only create one instance, since at most one instance can be active.\n     */\n    @Override\n    protected int createInstances(DelegateExecution multiInstanceRootExecution) {\n\n        int nrOfInstances = resolveNrOfInstances(multiInstanceRootExecution);\n        if (nrOfInstances == 0) {\n            return nrOfInstances;\n        } else if (nrOfInstances < 0) {\n            throw new FlowableIllegalArgumentException(\"Invalid number of instances: must be a non-negative integer value\" + \", but was \" + nrOfInstances);\n        }\n\n        // Create child execution that will execute the inner behavior\n        ExecutionEntity execution = CommandContextUtil.getExecutionEntityManager()\n                .createChildExecution((ExecutionEntity) multiInstanceRootExecution);\n        execution.setCurrentFlowElement(multiInstanceRootExecution.getCurrentFlowElement());\n\n        // Set Multi-instance variables\n        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_INSTANCES, nrOfInstances);\n        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_COMPLETED_INSTANCES, 0);\n        setLoopVariable(multiInstanceRootExecution, NUMBER_OF_ACTIVE_INSTANCES, 1);\n        logLoopDetails(multiInstanceRootExecution, \"initialized\", 0, 0, 1, nrOfInstances);\n\n        executeOriginalBehavior(execution, (ExecutionEntity) multiInstanceRootExecution, 0);\n\n        return nrOfInstances;\n    }\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/SequentialMultiInstanceBehavior.java#L32-L68","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nloopCardinality: ${items.size() - 1}\n// after\nloopCardinality: ${Math.max(0, items.size() - 1)}","handlingStrategy":"validation","validationCode":"// Guard loop cardinality before the multi-instance activity\nint nr = resolveNrOfInstances(execution);\nif (nr < 0) {\n    throw new IllegalArgumentException(\"nrOfInstances must be >= 0, was \" + nr);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp arithmetic expressions with Math.max(0, ...)","Test multi-instance expressions against empty and small collections","Avoid computing cardinality from mutable counters"],"tags":["multi-instance","expression","validation","flowable"],"backgroundTag":"value-out-of-range","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}