flowable/flowable-engine · error · FlowableIllegalArgumentException

Value is not a list of JPA entities:

Error message

Value is not a list of JPA entities: 

What it means

JPAEntityListVariableType.setValue only accepts null, a value resolvable to an entity class name, or a List of JPA entities. If the value is neither (some other object type), it throws FlowableIllegalArgumentException stating the value is not a list of JPA entities.

Source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityListVariableType.java:117

        }

        if (value instanceof List<?> list && list.size() > 0) {
            List<String> ids = new ArrayList<>();

            String type = mappings.getJPAClassString(list.get(0));
            for (Object entry : list) {
                ids.add(mappings.getJPAIdString(entry));
            }

            // Store type in text field and the ID's as a serialized array
            valueFields.setBytes(serializeIds(ids));
            valueFields.setTextValue(type);

        } else if (value == null) {
            valueFields.setBytes(null);
            valueFields.setTextValue(null);
        } else {
            throw new FlowableIllegalArgumentException("Value is not a list of JPA entities: " + value);
        }

    }

    @Override
    public Object getValue(ValueFields valueFields) {
        byte[] bytes = valueFields.getBytes();
        if (valueFields.getTextValue() != null && bytes != null) {
            String entityClass = valueFields.getTextValue();

            List<Object> result = new ArrayList<>();
            String[] ids = deserializeIds(bytes);

            for (String id : ids) {
                result.add(mappings.getJPAEntity(entityClass, id));
            }

            return result;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a java.util.List of JPA-annotated entities, or null to clear
2. Ensure each element is an entity recognized by Flowable's entity scanner (@Entity annotated)
3. Use JPAEntityVariableType for a single entity instead of the list type
4. Verify no earlier variable with the same name forced this type via setVariable type detection

Example fix

// before
runtimeService.setVariable(executionId, "customers", singleCustomer); // wrong type for list var
// after
runtimeService.setVariable(executionId, "customers", java.util.Arrays.asList(customerA, customerB));

boolean validListValue(Object v) {
    return v == null || (v instanceof java.util.List
        && ((java.util.List<?>) v).stream().allMatch(e -> e.getClass().isAnnotationPresent(jakarta.persistence.Entity.class)));
}

boolean isJpaEntityList(Object v) { return v instanceof java.util.List && !((java.util.List<?>) v).isEmpty() && ((java.util.List<?>) v).stream().allMatch(e -> e.getClass().isAnnotationPresent(jakarta.persistence.Entity.class)); }

try { runtimeService.setVariable(executionId, "customers", value); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().startsWith("Value is not a list of JPA entities")) { throw new IllegalArgumentException("Pass a List<JPA-entity> or null"); } throw e; }

When it happens

Trigger: Setting a variable whose VariableType resolves to JPAEntityListVariableType with a non-list, non-entity object (e.g. a plain String, Map, or single non-entity POJO), causing execution to fall into the final else branch.

Common situations: Passing a single entity where the variable type expects a List; passing a collection of non-entities; type confusion when reusing an existing variable slot previously bound to a JPA list type.

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

• EntityManagerFactory must implement 'jakarta.persistence.Ent
• Cannot set JPA variable:
• Value is not a list of JPA entities: " + value
• Cannot work with cached variables in an active command.
• Setting variable is not supported for read only delegate exe

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