flowable/flowable-engine · error · FlowableIllegalArgumentException

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

If the queried value resolves to JPAEntityListVariableType (a variable holding a list of JPA entities), Flowable cannot build a SQL predicate for it at all, and throws FlowableIllegalArgumentException("Variables containing a list of JPA entities cannot be used to query") at QueryVariableValue.java:64.

Source

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

        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() {
        if (operator != null) {
            return operator.toString();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Do not use list-of-entities variables in query predicates; query a scalar variable instead.
2. Store the entity ids in a String list variable and use variableValueEquals on a single id.
3. Retrieve candidates with a broader query and filter the list variable in application code.

Example fix

// before
taskQuery.variableValueEquals("orders", orderEntityList); // throws

// after
taskQuery.variableValueEquals("primaryOrderId", order.getId());

if (value instanceof java.util.List && isJpaEntityList((java.util.List<?>) value)) {
    throw new IllegalArgumentException("Lists of JPA entities cannot be used in variable queries");
}

static boolean isJpaEntityList(java.util.List<?> list) {
    return list != null && !list.isEmpty()
        && list.get(0).getClass().isAnnotationPresent(jakarta.persistence.Entity.class);
}

try {
    taskQuery.variableValueEquals("orders", entityList);
} catch (FlowableIllegalArgumentException e) {
    // query a scalar representative instead
    taskQuery.variableValueEquals("primaryOrderId", primaryOrder.getId());
}

When it happens

Trigger: Calling any variableValue* operator with a List<JPA-entity> value, e.g. taskQuery.variableValueEquals("orders", orderList) where orders is a list of JPA entities.

Common situations: Passing collection-valued JPA variables into query predicates assuming list support; querying serialized entity collections after upgrading to JPA variable handling.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Variables of type ByteArray cannot be used to query
• JPA entity variables can only be used in 'variableValueEqual
• Unsupported Primary key type for JPA-Entity: ${type}
• Variables of type ByteArray cannot be used to query
• JPA entity variables can only be used in 'variableValueEqual

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