flowable/flowable-engine · error · ActivitiIllegalArgumentException

Variables containing a list of JPA entities cannot be used t

Error message

Variables containing a list of JPA entities cannot be used to query

What it means

Variables containing a list of JPA entities (JPAEntityListVariableType) cannot be used in variable queries at all. List-of-entities variables are stored in a way that cannot be matched in SQL, so any query variable value resolving to this type throws ActivitiIllegalArgumentException.

Source

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

    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

Query on a scalar companion variable instead (e.g. store orderIds as List<Long> of ids or a single id).
Store the entity ids in a queryable variable type (List of serializable ids) and query with variableValueEquals on individual ids.
Fetch the candidate process instances first and filter in memory on the list variable's contents.
Catch ActivitiIllegalArgumentException and route to the id-based query path.

Example fix

// before
query.variableValueEquals("orders", orderEntities); // List<JPA entity>

// after
query.variableValueEquals("orderId", orderEntity.getId());

Defensive patterns

Strategy: validation

Validate before calling

if (value instanceof java.util.Collection<?> c && !c.isEmpty()
        && c.iterator().next().getClass().isAnnotationPresent(jakarta.persistence.Entity.class)) {
    throw new IllegalArgumentException("Lists of JPA entities cannot be used in variable queries");
}
query.variableValueEquals(name, value);

Type guard

boolean isJpaEntityList(Object v) {
    return v instanceof java.util.Collection<?> c && !c.isEmpty()
        && c.iterator().next().getClass().isAnnotationPresent(jakarta.persistence.Entity.class);
}

Try / catch

try {
    query.variableValueEquals(name, entityList);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // query an id-based companion variable instead
}

Prevention

Avoid storing JPA entity collections as process variables; store ids instead.
Query scalar id variables, not entity lists.
Filter in memory over list variables if entity-list matching is unavoidable.

When it happens

Trigger: Calling any variableValue* method on a query with a List<JPA entity> (or List of JPA-annotated objects) as the value.

Common situations: Storing related entity collections (e.g. a list of Order entities) as a process variable and later trying to find processes by one of those entities; JPA integration enabled and lists passed through variable APIs.

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

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