{"record":{"id":"7d8d5968caa85ff1","repo":"flowable/flowable-engine","slug":"delegateclassname-doesn-t-implement-flowablecoll","errorCode":null,"errorMessage":"<delegateClassName> doesn't implement FlowableCollectionHandler","messagePattern":"<delegateClassName> doesn't implement FlowableCollectionHandler","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/helper/ClassDelegateCollectionHandler.java","lineNumber":54,"sourceCode":"        super(className, fieldDeclarations);\n    }\n    \n    public ClassDelegateCollectionHandler(Class<?> clazz, List<FieldDeclaration> fieldDeclarations) {\n        super(clazz, fieldDeclarations);\n    }\n\n\t@Override\n\t@SuppressWarnings(\"rawtypes\")\n\tpublic Collection resolveCollection(Object collectionValue, DelegateExecution execution) {\n\t\treturn getCollectionHandlerInstance().resolveCollection(collectionValue, execution);\n\t}\n\n    protected FlowableCollectionHandler getCollectionHandlerInstance() {\n        Object delegateInstance = instantiateDelegate(className, fieldDeclarations);\n        if (delegateInstance instanceof FlowableCollectionHandler) {\n            return (FlowableCollectionHandler) delegateInstance;\n        } else {\n            throw new FlowableIllegalArgumentException(delegateInstance.getClass().getName() + \" doesn't implement \" + FlowableCollectionHandler.class);\n        }\n    }\n}\n","sourceCodeStart":36,"sourceCodeEnd":58,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/bpmn/helper/ClassDelegateCollectionHandler.java#L36-L58","documentation":"ClassDelegateCollectionHandler instantiates the class configured as a collection handler for multi-instance activities and casts it to FlowableCollectionHandler. If the instance does not implement that interface, a FlowableIllegalArgumentException naming the class and the expected interface is thrown. The engine needs this interface to resolve the collection of items a multi-instance activity iterates over.","triggerScenarios":"A multi-instance activity declares a collection handler class (flowable:collectionHandler / delegateExpression style config) whose class does not implement org.flowable.engine.delegate.FlowableCollectionHandler; resolveCollection triggers the check.","commonSituations":"Using an ordinary List-returning bean class instead of a FlowableCollectionHandler implementation; wrong class name in the BPMN XML; refactoring removed the interface; stale deployment jar.","solutions":["Make the configured class implement org.flowable.engine.delegate.FlowableCollectionHandler (getCollection(DelegateExecution)).","Verify the XML attribute points to the intended fully qualified handler class.","If the collection is static or expression-based, use flowable:collection with an expression instead of a handler class.","Redeploy the process application with the corrected handler."],"exampleFix":"// before\npublic class MyCollection { public List<String> items() { ... } }\n// after\npublic class MyCollection implements FlowableCollectionHandler {\n    @Override public Collection<String> getCollection(DelegateExecution execution) { ... }\n}","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(handlerClass);\nif (!FlowableCollectionHandler.class.isAssignableFrom(c))\n    throw new IllegalStateException(\"Collection handler must implement FlowableCollectionHandler\");","typeGuard":"boolean isValidHandler(Object o) { return o instanceof FlowableCollectionHandler; }","tryCatchPattern":"try {\n    runtimeService.startProcessInstanceByKey(\"proc\");\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"FlowableCollectionHandler\")) { /* fix handler class */ }\n    throw e;\n}","preventionTips":["Implement FlowableCollectionHandler for handler-class based multi-instance collections.","Prefer expression collections when a simple list suffices.","Validate handler classes at deployment time."],"tags":["flowable","delegate","multi-instance","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}