{"record":{"id":"0db776c4a458b4a7","repo":"flowable/flowable-engine","slug":"jpa-entity-variables-can-only-be-used-in-variable-0db776","errorCode":null,"errorMessage":"JPA entity variables can only be used in 'variableValueEquals'","messagePattern":"JPA entity variables can only be used in 'variableValueEquals'","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java","lineNumber":53,"sourceCode":"    private QueryOperator operator;\n\n    private VariableInstanceEntity variableInstanceEntity;\n    private boolean local;\n\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(\"JPA entity variables can only be used in 'variableValueEquals'\");\n            } else if (type instanceof JPAEntityListVariableType) {\n                throw new ActivitiIllegalArgumentException(\"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                variableInstanceEntity = VariableInstanceEntity.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();\n        }\n        return QueryOperator.EQUALS.toString();","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java#L35-L71","documentation":"JPA entity variables can only be queried with exact equality (variableValueEquals) when used as query variable values. Using a JPA entity variable with any other operator (greaterThan, like, notEquals, etc.) throws ActivitiIllegalArgumentException because only equality can be mapped to the entity's primary-key column.","triggerScenarios":"Calling variableValueGreaterThan / variableValueLessThan / variableValueLike / variableValueNotEquals (or IN variants) with a JPA entity object as the value on a query.","commonSituations":"Mixing JPA integration with variable queries and assuming general comparison operators work on entity variables; refactoring a query from String values to entity references while keeping a non-equals operator.","solutions":["Use variableValueEquals (or variableValueEqualsIgnoreCase where applicable) when the value is a JPA entity.","Query instead on the entity's primary key stored in a separate plain variable and apply any operator you need to that.","Fetch matching entities first via JPA, then query by their ids using variableValueEquals/IN-style equality only.","Catch ActivitiIllegalArgumentException and fall back to the primary-key-based query."],"exampleFix":"// before\nquery.variableValueGreaterThan(\"customer\", customerEntity);\n\n// after\nquery.variableValueEquals(\"customerId\", customerEntity.getId());","handlingStrategy":"validation","validationCode":"if (isJpaEntity(value) && operator != Operator.EQUALS) {\n    throw new IllegalArgumentException(\"JPA entity variables support only variableValueEquals\");\n}\nquery.variableValueEquals(name, value);","typeGuard":"boolean isJpaEntity(Object v) {\n    return v != null && v.getClass().isAnnotationPresent(jakarta.persistence.Entity.class);\n}","tryCatchPattern":"try {\n    query.variableValueGreaterThan(name, value);\n} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {\n    // switch to equality on a primary-key variable\n}","preventionTips":["Query JPA entity variables only with variableValueEquals.","Store entity ids in separate scalar variables for range/like queries.","Document which process variables are JPA-backed so query authors know the restriction."],"tags":["query","jpa","variables","unsupported-operator","activiti"],"backgroundTag":"unsupported-operation","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"}