{"record":{"id":"12bd057fb2102a0f","repo":"Activiti/Activiti","slug":"variables-containing-a-list-of-jpa-entities-cannot","errorCode":null,"errorMessage":"Variables containing a list of JPA entities cannot be used to query","messagePattern":"Variables containing a list of JPA entities cannot be used to query","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java","lineNumber":60,"sourceCode":"\n    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local) {\n        this.name = name;\n        this.value = value;\n        this.operator = operator;\n        this.local = local;\n    }\n\n    public void initialize(VariableTypes types) {\n        if (variableInstanceEntity == null) {\n            VariableType type = types.findVariableType(value);\n            if (type instanceof ByteArrayType) {\n                throw new ActivitiIllegalArgumentException(\"Variables of type ByteArray cannot be used to query\");\n            } else if (type instanceof JPAEntityVariableType && operator != QueryOperator.EQUALS) {\n                throw new ActivitiIllegalArgumentException(\n                    \"JPA entity variables can only be used in 'variableValueEquals'\"\n                );\n            } else if (type instanceof JPAEntityListVariableType) {\n                throw new ActivitiIllegalArgumentException(\n                    \"Variables containing a list of JPA entities cannot be used to query\"\n                );\n            } else {\n                // Type implementation determines which fields are set on the entity\n                variableInstanceEntity = Context.getCommandContext()\n                    .getVariableInstanceEntityManager()\n                    .create(name, type, value);\n            }\n        }\n    }\n\n    public String getName() {\n        return name;\n    }\n\n    public String getOperator() {\n        if (operator != null) {\n            return operator.toString();","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/Activiti/Activiti/blob/56435b1a97deeafdc09dd40074b056c89fba5a8a/activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java#L42-L78","documentation":"If a query variable value resolves to JPAEntityListVariableType (a variable holding a list of JPA entities), it cannot be used in any variable query at all, including equality. QueryVariableValue.initialize() throws this ActivitiIllegalArgumentException because list-of-entity variables have no single-value SQL comparison semantics.","triggerScenarios":"Calling any processInstanceQuery/taskQuery variableValueXxx(...) method passing a List<JPA entity> as the value, e.g. variableValueEquals(\"orders\", orderList).","commonSituations":"Storing collections of JPA entities as multi-instance/list process variables and later trying to filter process instances by the whole collection; migrating query code after converting a scalar entity variable into a list.","solutions":["Query on a scalar companion variable (e.g. primary entity id or count) instead of the list variable","Iterate and query per element (e.g. variableValueEquals on each entity's id) and combine results","Avoid storing JPA entity lists as process variables; store serializable DTOs or foreign keys"],"exampleFix":"// before\nprocessInstanceQuery.variableValueEquals(\"orders\", orderEntities);\n// after\nprocessInstanceQuery.variableValueEquals(\"primaryOrderId\", primaryOrder.getId());","handlingStrategy":"validation","validationCode":"if (value instanceof java.util.Collection) {\n    throw new IllegalArgumentException(\"Collections of JPA entities cannot be used in variable queries\");\n}","typeGuard":"boolean isQueryable(Object v) {\n    return !(v instanceof java.util.Collection) || !containsJpaEntities((java.util.Collection<?>) v);\n}","tryCatchPattern":"try {\n    query.variableValueEquals(name, listValue);\n} catch (ActivitiIllegalArgumentException e) {\n    // switch to querying a scalar companion variable\n}","preventionTips":["Never use list-of-JPA-entities variables as query filters","Model list variables as serializable DTOs or foreign-key strings","Query per-element or via a companion scalar variable"],"tags":["activiti","query","jpa","variables","list","unsupported"],"backgroundTag":"unsupported-operation","analyzedSha":"56435b1a97deeafdc09dd40074b056c89fba5a8a","analyzedAt":"2026-09-09T21:00:06.703Z","contentChangedAt":"2026-09-09T21:00:06.703Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}