flowable/flowable-engine · error · FlowableIllegalArgumentException

JPA entity variables can only be used in 'variableValueEqual

Error message

JPA entity variables can only be used in 'variableValueEquals'

What it means

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.

Source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/QueryVariableValue.java:62

    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local) {
        this.name = name;
        this.value = value;
        this.operator = operator;
        this.local = local;
    }

    public QueryVariableValue(String name, Object value, QueryOperator operator, boolean local, String scopeType) {
        this(name, value, operator, local);
        this.scopeType = scopeType;
    }

    public void initialize(VariableValueProvider valueProvider) {
        if (valueField == null) {
            valueType = valueProvider.findVariableType(value);
            if (valueType instanceof ByteArrayType) {
                throw new FlowableIllegalArgumentException("Variables of type ByteArray cannot be used to query");
            } else if (valueType instanceof JPAEntityVariableType && operator != QueryOperator.EQUALS) {
                throw new FlowableIllegalArgumentException("JPA entity variables can only be used in 'variableValueEquals'");
            } else if (valueType instanceof JPAEntityListVariableType) {
                throw new FlowableIllegalArgumentException("Variables containing a list of JPA entities cannot be used to query");
            } else {
                // Type implementation determines which fields are set on the entity
                valueField = valueProvider.createValueFields(name, valueType, value);
            }
        }
    }

    public void initialize(VariableServiceConfiguration variableServiceConfiguration) {
        initialize(new VariableServiceConfigurationVariableValueProvider(variableServiceConfiguration));
    }

    public String getName() {
        return name;
    }

    public String getOperator() {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Use variableValueEquals(entityIdOrEntity) for JPA entity variables.
2. Query by the entity's id stored in a separate String/Long variable instead.
3. Enable JPA-style equality only; perform other comparisons on a scalar shadow variable.

Example fix

// before
taskQuery.variableValueNotEquals("customer", customer); // throws

// after
taskQuery.variableValueEquals("customerId", customer.getId());

if (isJpaEntity(value) && !operatorIsEquals) {
    throw new IllegalArgumentException("Use variableValueEquals for JPA entity variables");
}

static boolean isJpaEntity(Object v) {
    return v != null && v.getClass().isAnnotationPresent(jakarta.persistence.Entity.class);
}

try {
    taskQuery.variableValueGreaterThan("customer", entity);
} catch (FlowableIllegalArgumentException e) {
    // re-run with equality on the entity id
    taskQuery.variableValueEquals("customerId", entity.getId());
}

When it happens

Trigger: Calling variableValueNotEquals/variableValueGreaterThan/etc. with a JPA entity value, e.g. taskQuery.variableValueGreaterThan("customer", customerEntity); the guard requires operator == QueryOperator.EQUALS.

Common situations: JPA variable support enabled and entity-valued variables used with range or inequality filters; copying a query snippet and changing only the operator name.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• JPA entity variables can only be used in 'variableValueEqual
• Variables containing a list of JPA entities cannot be used t
• Variables containing a list of JPA entities cannot be used t
• appsDefinitionIds is null
• Empty appsDefinitionIds

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/0b2170d71e026694. Report an issue: GitHub.