{"record":{"id":"da2dfff7d2957cdd","repo":"flowable/flowable-engine","slug":"couldn-t-resolve-collection-expression-nor-variabl","errorCode":null,"errorMessage":"Couldn't resolve collection expression nor variable reference","messagePattern":"Couldn't resolve collection expression nor variable reference","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/MultiInstanceActivityBehavior.java","lineNumber":459,"sourceCode":"        return FlowableEventBuilder.createMultiInstanceActivityCompletedEvent(eventType,\n                getLoopVariable(execution, NUMBER_OF_INSTANCES),\n                getLoopVariable(execution, NUMBER_OF_ACTIVE_INSTANCES),\n                getLoopVariable(execution, NUMBER_OF_COMPLETED_INSTANCES),\n                flowNode.getId(),\n                flowNode.getName(), execution.getId(), execution.getProcessInstanceId(), execution.getProcessDefinitionId(), flowNode);\n    }\n\n    @SuppressWarnings(\"rawtypes\")\n    protected int resolveNrOfInstances(DelegateExecution execution) {\n        if (loopCardinalityExpression != null) {\n            return resolveLoopCardinality(execution);\n\n        } else if (usesCollection()) {\n            Collection collection = resolveAndValidateCollection(execution);\n            return collection.size();\n\n        } else {\n            throw new FlowableIllegalArgumentException(\"Couldn't resolve collection expression nor variable reference\");\n        }\n    }\n\n    @SuppressWarnings(\"rawtypes\")\n    protected void executeOriginalBehavior(DelegateExecution execution, ExecutionEntity multiInstanceRootExecution, int loopCounter) {\n        if (usesCollection() && collectionElementVariable != null) {\n            Collection collection = resolveAndValidateCollection(execution);\n\n            Object value = null;\n            int index = 0;\n            Iterator it = collection.iterator();\n            while (index <= loopCounter) {\n                value = it.next();\n                index++;\n            }\n            setLoopVariable(execution, collectionElementVariable, value);\n        }\n","sourceCodeStart":441,"sourceCodeEnd":477,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/behavior/MultiInstanceActivityBehavior.java#L441-L477","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: variable never set, process starts the multi-instance task\n// after: initialize the collection before the multi-instance activity\n<serviceTask id=\"initList\" flowable:expression=\"${'a,b,c'.split(',')}\">\n  <extensionElements>\n    <flowable:out source=\"x\" target=\"assigneeList\"/>\n  </extensionElements>\n</serviceTask>","handlingStrategy":"validation","validationCode":"if (execution.getVariable(\"assigneeList\") == null) {\n    throw new IllegalStateException(\"Collection variable 'assigneeList' must be set before the multi-instance activity\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return task.execute(execution);\n} catch (FlowableIllegalArgumentException ex) {\n    if (ex.getMessage().contains(\"Couldn't resolve collection\")) {\n        logger.error(\"Multi-instance collection not configured/resolvable: {}\", ex.getMessage());\n    }\n    throw ex;\n}","preventionTips":["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."],"tags":["bpmn","multi-instance","collection","process-variables"],"backgroundTag":"missing-required-argument","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"}