flowable/flowable-engine · error · ActivitiIllegalArgumentException

JPA entity variables can only be used in 'variableValueEqual

Error message

JPA entity variables can only be used in 'variableValueEquals'

What it means

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.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java:53

    private QueryOperator operator;

    private VariableInstanceEntity variableInstanceEntity;
    private boolean local;

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

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

    public String getName() {
        return name;
    }

    public String getOperator() {
        if (operator != null) {
            return operator.toString();
        }
        return QueryOperator.EQUALS.toString();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Use variableValueEquals (or variableValueEqualsIgnoreCase where applicable) when the value is a JPA entity.
2. Query instead on the entity's primary key stored in a separate plain variable and apply any operator you need to that.
3. Fetch matching entities first via JPA, then query by their ids using variableValueEquals/IN-style equality only.
4. Catch ActivitiIllegalArgumentException and fall back to the primary-key-based query.

Example fix

// before
query.variableValueGreaterThan("customer", customerEntity);

// after
query.variableValueEquals("customerId", customerEntity.getId());

if (isJpaEntity(value) && operator != Operator.EQUALS) {
    throw new IllegalArgumentException("JPA entity variables support only variableValueEquals");
}
query.variableValueEquals(name, value);

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

try {
    query.variableValueGreaterThan(name, value);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // switch to equality on a primary-key variable
}

When it happens

Trigger: Calling variableValueGreaterThan / variableValueLessThan / variableValueLike / variableValueNotEquals (or IN variants) with a JPA entity object as the value on a query.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Variables containing a list of JPA entities cannot be used t
• JPA entity variables can only be used in 'variableValueEqual
• Variables of type ByteArray cannot be used to query
• Cannot set JPA variable: " + EntityManagerSession.class + "
• Value is not a list of JPA entities: " + value

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