{"record":{"id":"e11e6ded84d51052","repo":"flowable/flowable-engine","slug":"object-is-not-a-jpa-entity-class-class-va","errorCode":null,"errorMessage":"Object is not a JPA Entity: class='${class}', ${value}","messagePattern":"Object is not a JPA Entity: class='(.+?)', (.+?)","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityMappings.java","lineNumber":74,"sourceCode":"            // Class not present in meta-data map, create metaData for it and add\n            metaData = scanClass(clazz);\n            classMetaDatamap.put(clazz.getName(), metaData);\n        }\n        return metaData;\n    }\n\n    private EntityMetaData scanClass(Class<?> clazz) {\n        return enitityScanner.scanClass(clazz);\n    }\n\n    public String getJPAClassString(Object value) {\n        if (value == null) {\n            throw new FlowableIllegalArgumentException(\"null value cannot be saved\");\n        }\n\n        EntityMetaData metaData = getEntityMetaData(value.getClass());\n        if (!metaData.isJPAEntity()) {\n            throw new FlowableIllegalArgumentException(\"Object is not a JPA Entity: class='\" + value.getClass() + \"', \" + value);\n        }\n\n        // Extract the class from the Entity instance\n        return metaData.getEntityClass().getName();\n    }\n\n    public String getJPAIdString(Object value) {\n        EntityMetaData metaData = getEntityMetaData(value.getClass());\n        if (!metaData.isJPAEntity()) {\n            throw new FlowableIllegalArgumentException(\"Object is not a JPA Entity: class='\" + value.getClass() + \"', \" + value);\n        }\n        Object idValue = getIdValue(value, metaData);\n        return getIdString(idValue);\n    }\n\n    public Object getIdValue(Object value, EntityMetaData metaData) {\n        try {\n            if (metaData.getIdMethod() != null) {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityMappings.java#L56-L92","documentation":"After resolving EntityMetaData for the value's class, getJPAClassString verifies the class is actually a JPA entity (per Flowable's entity scanner). If not, it throws FlowableIllegalArgumentException reporting the class and value.","triggerScenarios":"Storing a variable whose class was not scanned as an @Entity — plain POJOs, non-entity classes, or entities from a persistence unit Flowable doesn't know — reaches the isJPAEntity check and fails.","commonSituations":"Entity class missing @Entity or not listed in persistence.xml; JPA entity scanner configured with a wrong package/persistence unit; using flowable's JPA variable types for non-JPA domain objects; multiple persistence units where the engine scans only one.","solutions":["Annotate the class with @Entity and register it in persistence.xml (or the scanned persistence unit)","Verify jpaPersistenceUnitName/jpaEntityManagerFactory points at the unit containing the entity","Confirm the class name and classloader (no duplicate classes across JARs confusing the scanner)","Use a plain serializable variable type for non-entity objects instead of JPA types"],"exampleFix":"// before\npublic class CustomerDto { ... } // not an entity\nengineConfig.setJpaEntityManagerFactory(emfFor(\"other-pu\"));\n// after\n@Entity\npublic class Customer { ... } // registered in the configured persistence unit\nengineConfig.setJpaPersistenceUnitName(\"correct-pu\");","handlingStrategy":"type-guard","validationCode":"boolean isRegisteredEntity(Object v) {\n    return v != null && v.getClass().isAnnotationPresent(jakarta.persistence.Entity.class);\n}","typeGuard":"boolean isJpaEntity(Object v) { return v != null && v.getClass().isAnnotationPresent(jakarta.persistence.Entity.class); }","tryCatchPattern":"try { runtimeService.setVariable(executionId, \"customer\", obj); } catch (FlowableIllegalArgumentException e) { if (e.getMessage().startsWith(\"Object is not a JPA Entity\")) { throw new IllegalArgumentException(\"Register \" + obj.getClass() + \" in the scanned persistence unit\"); } throw e; }","preventionTips":["Annotate classes with @Entity and list them in the persistence unit Flowable scans","Keep jpaPersistenceUnitName aligned with the unit holding your entities","Don't store DTOs through JPA variable types — use serializable variables for non-entities"],"tags":["jpa","entity","configuration","flowable"],"backgroundTag":"type-mismatch","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"}