{"record":{"id":"0b2170d71e026694","repo":"flowable/flowable-engine","slug":"jpa-entity-variables-can-only-be-used-in-variable","errorCode":null,"errorMessage":"JPA entity variables can only be used in 'variableValueEquals'","messagePattern":"JPA entity variables can only be used in 'variableValueEquals'","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java","lineNumber":62,"sourceCode":"    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 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() {","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java#L44-L80","documentation":"When the queried value resolves to JPAEntityVariableType, Flowable can only match it with an EQUALS comparison, since JPA entity variables are stored by id/reference and no other SQL operator is supported. Using them with any other operator (notEquals, like, greaterThan, etc.) raises FlowableIllegalArgumentException(\"JPA entity variables can only be used in 'variableValueEquals'\") at QueryVariableValue.java:62.","triggerScenarios":"Calling variableValueNotEquals/variableValueGreaterThan/etc. with a JPA entity value, e.g. taskQuery.variableValueGreaterThan(\"customer\", customerEntity); the guard requires operator == QueryOperator.EQUALS.","commonSituations":"JPA variable support enabled and entity-valued variables used with range or inequality filters; copying a query snippet and changing only the operator name.","solutions":["Use variableValueEquals(entityIdOrEntity) for JPA entity variables.","Query by the entity's id stored in a separate String/Long variable instead.","Enable JPA-style equality only; perform other comparisons on a scalar shadow variable."],"exampleFix":"// before\ntaskQuery.variableValueNotEquals(\"customer\", customer); // throws\n\n// after\ntaskQuery.variableValueEquals(\"customerId\", customer.getId());","handlingStrategy":"type-guard","validationCode":"if (isJpaEntity(value) && !operatorIsEquals) {\n    throw new IllegalArgumentException(\"Use variableValueEquals for JPA entity variables\");\n}","typeGuard":"static boolean isJpaEntity(Object v) {\n    return v != null && v.getClass().isAnnotationPresent(jakarta.persistence.Entity.class);\n}","tryCatchPattern":"try {\n    taskQuery.variableValueGreaterThan(\"customer\", entity);\n} catch (FlowableIllegalArgumentException e) {\n    // re-run with equality on the entity id\n    taskQuery.variableValueEquals(\"customerId\", entity.getId());\n}","preventionTips":["Restrict JPA entity values to variableValueEquals only.","Prefer querying a scalar id variable over the entity variable.","Centralize variable query construction so operator/entity combinations are checked once."],"tags":["query","jpa","unsupported-operator"],"backgroundTag":"invalid-argument-value","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"}