{"record":{"id":"cbad1d6e24934522","repo":"flowable/flowable-engine","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":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java","lineNumber":64,"sourceCode":"        this.value = value;\n        this.operator = operator;\n        this.local = local;\n    }\n\n    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local, String scopeType) {\n        this(name, value, operator, local);\n        this.scopeType = scopeType;\n    }\n\n    public void initialize(VariableValueProvider valueProvider) {\n        if (valueField == null) {\n            valueType = valueProvider.findVariableType(value);\n            if (valueType instanceof ByteArrayType) {\n                throw new FlowableIllegalArgumentException(\"Variables of type ByteArray cannot be used to query\");\n            } else if (valueType instanceof JPAEntityVariableType && operator != QueryOperator.EQUALS) {\n                throw new FlowableIllegalArgumentException(\"JPA entity variables can only be used in 'variableValueEquals'\");\n            } else if (valueType instanceof JPAEntityListVariableType) {\n                throw new FlowableIllegalArgumentException(\"Variables containing a list of JPA entities cannot be used to query\");\n            } else {\n                // Type implementation determines which fields are set on the entity\n                valueField = valueProvider.createValueFields(name, valueType, value);\n            }\n        }\n    }\n\n    public void initialize(VariableServiceConfiguration variableServiceConfiguration) {\n        initialize(new VariableServiceConfigurationVariableValueProvider(variableServiceConfiguration));\n    }\n\n    public String getName() {\n        return name;\n    }\n\n    public String getOperator() {\n        if (operator != null) {\n            return operator.toString();","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java#L46-L82","documentation":"If the queried value resolves to JPAEntityListVariableType (a variable holding a list of JPA entities), Flowable cannot build a SQL predicate for it at all, and throws FlowableIllegalArgumentException(\"Variables containing a list of JPA entities cannot be used to query\") at QueryVariableValue.java:64.","triggerScenarios":"Calling any variableValue* operator with a List<JPA-entity> value, e.g. taskQuery.variableValueEquals(\"orders\", orderList) where orders is a list of JPA entities.","commonSituations":"Passing collection-valued JPA variables into query predicates assuming list support; querying serialized entity collections after upgrading to JPA variable handling.","solutions":["Do not use list-of-entities variables in query predicates; query a scalar variable instead.","Store the entity ids in a String list variable and use variableValueEquals on a single id.","Retrieve candidates with a broader query and filter the list variable in application code."],"exampleFix":"// before\ntaskQuery.variableValueEquals(\"orders\", orderEntityList); // throws\n\n// after\ntaskQuery.variableValueEquals(\"primaryOrderId\", order.getId());","handlingStrategy":"type-guard","validationCode":"if (value instanceof java.util.List && isJpaEntityList((java.util.List<?>) value)) {\n    throw new IllegalArgumentException(\"Lists of JPA entities cannot be used in variable queries\");\n}","typeGuard":"static boolean isJpaEntityList(java.util.List<?> list) {\n    return list != null && !list.isEmpty()\n        && list.get(0).getClass().isAnnotationPresent(jakarta.persistence.Entity.class);\n}","tryCatchPattern":"try {\n    taskQuery.variableValueEquals(\"orders\", entityList);\n} catch (FlowableIllegalArgumentException e) {\n    // query a scalar representative instead\n    taskQuery.variableValueEquals(\"primaryOrderId\", primaryOrder.getId());\n}","preventionTips":["Never pass JPA entity collections to variableValue* methods.","Store ids in scalar variables for querying; keep entity lists for process payload only.","Filter list-valued variables in application code after a broader query."],"tags":["query","jpa","unsupported-type"],"backgroundTag":"incompatible-source-type","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"}