{"record":{"id":"00e12854cb7a9957","repo":"flowable/flowable-engine","slug":"class-is-not-a-jpa-entity","errorCode":null,"errorMessage":"Class is not a JPA-entity: ","messagePattern":"Class is not a JPA-entity: ","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityMappings.java","lineNumber":118,"sourceCode":"            throw new ActivitiException(\"Illegal argument exception when getting value from id method/field on JPAEntity\", iae);\n        } catch (IllegalAccessException iae) {\n            throw new ActivitiException(\"Cannot access id method/field for JPA Entity\", iae);\n        } catch (InvocationTargetException ite) {\n            throw new ActivitiException(\"Exception occurred while getting value from id field/method on JPAEntity: \" +\n                    ite.getCause().getMessage(), ite.getCause());\n        }\n\n        // Fall trough when no method and field is set\n        throw new ActivitiException(\"Cannot get id from JPA Entity, no id method/field set\");\n    }\n\n    public Object getJPAEntity(String className, String idString) {\n        Class<?> entityClass = null;\n        entityClass = ReflectUtil.loadClass(className);\n\n        EntityMetaData metaData = getEntityMetaData(entityClass);\n        if (metaData == null) {\n            throw new ActivitiIllegalArgumentException(\"Class is not a JPA-entity: \" + className);\n        }\n\n        // Create primary key of right type\n        Object primaryKey = createId(metaData, idString);\n        return findEntity(entityClass, primaryKey);\n    }\n\n    private Object findEntity(Class<?> entityClass, Object primaryKey) {\n        EntityManager em = Context\n                .getCommandContext()\n                .getSession(EntityManagerSession.class)\n                .getEntityManager();\n\n        Object entity = em.find(entityClass, primaryKey);\n        if (entity == null) {\n            throw new ActivitiException(\"Entity does not exist: \" + entityClass.getName() + \" - \" + primaryKey);\n        }\n        return entity;","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityMappings.java#L100-L136","documentation":"getJPAEntity loads an entity from its stored class name and id. Before doing so it resolves EntityMetaData for the class; a null result means the class is not recognized as a JPA entity, so the stored variable cannot be materialized.","triggerScenarios":"Deserializing a JPA entity variable whose stored class name no longer resolves to entity metadata — class renamed/moved, @Entity removed, or the variable was created with a non-entity class.","commonSituations":"Application upgrade renaming/moving entity packages so old process variables reference stale class names; entity removed from the persistence unit; typo in configured class name in a JPA variable lookup.","solutions":["Restore the class to its original package/name or keep a compatibility class so old variables still resolve","Re-annotate the class with @Entity and rebuild metadata","Migrate old variable rows (ACT_RU_VARIABLE / ACT_HI_VARINST) to the new class name","Remove or recreate the affected process variables"],"exampleFix":"// before\npackage com.old; @Entity public class Order {...}\n// after (moved)\npackage com.new; @Entity public class Order {...}\n// plus migration of stored class name com.old.Order -> com.new.Order","handlingStrategy":"validation","validationCode":"try {\n    Class<?> c = ReflectUtil.loadClass(className);\n    if (!c.isAnnotationPresent(Entity.class)) {\n        throw new IllegalArgumentException(className + \" is not an entity\");\n    }\n} catch (ActivitiException e) { /* stale class name in variables */ }","typeGuard":"boolean isResolvableEntity(String className) {\n    try {\n        return Class.forName(className).isAnnotationPresent(javax.persistence.Entity.class);\n    } catch (ClassNotFoundException e) { return false; }\n}","tryCatchPattern":"try {\n    Object entity = mappings.getJPAEntity(className, idString);\n} catch (ActivitiIllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"Class is not a JPA-entity\")) {\n        // migrate or delete stale variables referencing renamed classes\n    } else { throw e; }\n}","preventionTips":["Keep old entity FQCNs stable across releases or migrate variables","Never remove @Entity from classes referenced by process variables","Track entity renames with variable-data migration scripts"],"tags":["jpa","class-not-found","entity-mapping"],"backgroundTag":"class-not-found","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"}