Activiti/Activiti · error · ActivitiIllegalArgumentException

Variables containing a list of JPA entities cannot be used…

Error message

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

What it means

If a query variable value resolves to JPAEntityListVariableType (a variable holding a list of JPA entities), it cannot be used in any variable query at all, including equality. QueryVariableValue.initialize() throws this ActivitiIllegalArgumentException because list-of-entity variables have no single-value SQL comparison semantics.

Solutions

Query on a scalar companion variable (e.g. primary entity id or count) instead of the list variable
Iterate and query per element (e.g. variableValueEquals on each entity's id) and combine results
Avoid storing JPA entity lists as process variables; store serializable DTOs or foreign keys

Example fix

// before
processInstanceQuery.variableValueEquals("orders", orderEntities);
// after
processInstanceQuery.variableValueEquals("primaryOrderId", primaryOrder.getId());

Defensive patterns

Strategy: validation

Validate before calling

if (value instanceof java.util.Collection) {
    throw new IllegalArgumentException("Collections of JPA entities cannot be used in variable queries");
}

Type guard

boolean isQueryable(Object v) {
    return !(v instanceof java.util.Collection) || !containsJpaEntities((java.util.Collection<?>) v);
}

Try / catch

try {
    query.variableValueEquals(name, listValue);
} catch (ActivitiIllegalArgumentException e) {
    // switch to querying a scalar companion variable
}

Prevention

Never use list-of-JPA-entities variables as query filters
Model list variables as serializable DTOs or foreign-key strings
Query per-element or via a companion scalar variable

When it happens

Trigger: Calling any processInstanceQuery/taskQuery variableValueXxx(...) method passing a List<JPA entity> as the value, e.g. variableValueEquals("orders", orderList).

Common situations: Storing collections of JPA entities as multi-instance/list process variables and later trying to filter process instances by the whole collection; migrating query code after converting a scalar entity variable into a list.

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 Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/12bd057fb2102a0f. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/QueryVariableValue.java:60

    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 = Context.getCommandContext()
                    .getVariableInstanceEntityManager()
                    .create(name, type, value);
            }
        }
    }

    public String getName() {
        return name;
    }

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

View on GitHub (pinned to 56435b1a97)