{"record":{"id":"2c20d5e11e20cea6","repo":"flowable/flowable-engine","slug":"value-is-not-a-list-of-jpa-entities-value","errorCode":null,"errorMessage":"Value is not a list of JPA entities: \" + value","messagePattern":"Value is not a list of JPA entities: \" \\+ value","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityListVariableType.java","lineNumber":119,"sourceCode":"\n        if (value instanceof List<?> && ((List<?>) value).size() > 0) {\n            List<?> list = (List<?>) value;\n            List<String> ids = new ArrayList<>();\n\n            String type = mappings.getJPAClassString(list.get(0));\n            for (Object entry : list) {\n                ids.add(mappings.getJPAIdString(entry));\n            }\n\n            // Store type in text field and the ID's as a serialized array\n            valueFields.setBytes(serializeIds(ids));\n            valueFields.setTextValue(type);\n\n        } else if (value == null) {\n            valueFields.setBytes(null);\n            valueFields.setTextValue(null);\n        } else {\n            throw new ActivitiIllegalArgumentException(\"Value is not a list of JPA entities: \" + value);\n        }\n\n    }\n\n    @Override\n    public Object getValue(ValueFields valueFields) {\n        byte[] bytes = valueFields.getBytes();\n        if (valueFields.getTextValue() != null && bytes != null) {\n            String entityClass = valueFields.getTextValue();\n\n            List<Object> result = new ArrayList<>();\n            String[] ids = deserializeIds(bytes);\n\n            for (String id : ids) {\n                result.add(mappings.getJPAEntity(entityClass, id));\n            }\n\n            return result;","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityListVariableType.java#L101-L137","documentation":"Thrown by JPAEntityListVariableType.setValue() when the value being stored is neither null nor a List whose elements the type can treat as JPA entities. The type guards the shape of the incoming value before serialization and rejects anything else with ActivitiIllegalArgumentException.","triggerScenarios":"Calling runtimeService.setVariable(name, someObject) where someObject is a single entity, a String, or a non-entity list while JPAEntityListVariableType is selected as the variable type; passing a list of non-Serializable/non-entity objects.","commonSituations":"Passing a single JPA entity where a list type is expected (single entities go through JPAEntityVariableType); list elements not being entities at all; generics erasure hiding the wrong element type until runtime.","solutions":["Store single entities with JPAEntityVariableType (plain entity variable) instead of the list type","Ensure the value is a java.util.List of JPA-managed entity objects","Check variable-type resolution order if a custom type is shadowing the intended handler","Convert non-entity objects (DTOs) to JSON/serializable variables instead of JPA types"],"exampleFix":"// before\nruntimeService.setVariable(executionId, \"orders\", singleOrder); // list type, single entity\n// after\nruntimeService.setVariable(executionId, \"orders\", List.of(order1, order2));","handlingStrategy":"type-guard","validationCode":"// before setting the variable\nif (!(value instanceof List) || ((List<?>) value).isEmpty() || !entityClass.isInstance(((List<?>) value).get(0))) {\n    throw new IllegalArgumentException(\"Expected a List of JPA entities\");\n}","typeGuard":"boolean isJpaEntityList(Object v) {\n    return v instanceof List && !((List<?>) v).isEmpty()\n        && entityManager.getMetamodel().getEntities().stream()\n            .anyMatch(t -> t.getJavaType().isInstance(((List<?>) v).get(0)));\n}","tryCatchPattern":"try {\n    runtimeService.setVariable(executionId, \"orders\", orderList);\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Value is not a list of JPA entities\")) {\n        // handle single-entity vs list mismatch\n    }\n    throw e;\n}","preventionTips":["Use JPAEntityVariableType for single entities and JPAEntityListVariableType only for lists","Never rely on generics to enforce element types at runtime","Convert DTOs to dedicated (JSON/serializable) variables, not JPA types"],"tags":["jpa","variables","type-mismatch","activiti"],"backgroundTag":"invalid-argument-value","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}