{"record":{"id":"0c9728441dabdc22","repo":"flowable/flowable-engine","slug":"entitymanagerfactory-must-implement-jakarta-persi","errorCode":null,"errorMessage":"EntityManagerFactory must implement 'jakarta.persistence.EntityManagerFactory'","messagePattern":"EntityManagerFactory must implement 'jakarta\\.persistence\\.EntityManagerFactory'","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/EntityManagerSessionFactory.java","lineNumber":37,"sourceCode":"import org.flowable.common.engine.impl.interceptor.CommandContext;\nimport org.flowable.common.engine.impl.interceptor.Session;\nimport org.flowable.common.engine.impl.interceptor.SessionFactory;\n\n/**\n * @author Frederik Heremans\n */\npublic class EntityManagerSessionFactory implements SessionFactory {\n\n    protected EntityManagerFactory entityManagerFactory;\n    protected boolean handleTransactions;\n    protected boolean closeEntityManager;\n\n    public EntityManagerSessionFactory(Object entityManagerFactory, boolean handleTransactions, boolean closeEntityManager) {\n        if (entityManagerFactory == null) {\n            throw new FlowableIllegalArgumentException(\"entityManagerFactory is null\");\n        }\n        if (!(entityManagerFactory instanceof EntityManagerFactory)) {\n            throw new FlowableIllegalArgumentException(\"EntityManagerFactory must implement 'jakarta.persistence.EntityManagerFactory'\");\n        }\n\n        this.entityManagerFactory = (EntityManagerFactory) entityManagerFactory;\n        this.handleTransactions = handleTransactions;\n        this.closeEntityManager = closeEntityManager;\n    }\n\n    @Override\n    public Class<?> getSessionType() {\n        return EntityManagerSession.class;\n    }\n\n    @Override\n    public Session openSession(CommandContext commandContext) {\n        return new EntityManagerSessionImpl(entityManagerFactory, handleTransactions, closeEntityManager);\n    }\n\n    public EntityManagerFactory getEntityManagerFactory() {","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/EntityManagerSessionFactory.java#L19-L55","documentation":"EntityManagerSessionFactory's constructor performs an instanceof check after the null check: the argument must implement jakarta.persistence.EntityManagerFactory, otherwise FlowableIllegalArgumentException 'EntityManagerFactory must implement jakarta.persistence.EntityManagerFactory' is thrown.","triggerScenarios":"Passing an object that is not a jakarta.persistence.EntityManagerFactory (e.g. a Hibernate-specific SessionFactory, a Spring proxy of the wrong type, or a javax.persistence.EntityManagerFactory from a pre-Jakarta / older Flowable version).","commonSituations":"Migrating from Java EE (javax.persistence) to Jakarta (jakarta.persistence) — old Hibernate 5 / Spring Boot 2 factories no longer qualify; passing Hibernate's SessionFactoryImpl directly instead of the JPA EntityManagerFactory; wrong bean autowired.","solutions":["Pass a jakarta.persistence.EntityManagerFactory (e.g. Spring's LocalContainerEntityManagerFactoryBean.getObject() or Persistence.createEntityManagerFactory(...))","Upgrade to Hibernate 5.5+/6 or Spring Boot 3 so the factory implements jakarta.persistence.EntityManagerFactory","If stuck on javax.persistence, use a Flowable version matching that era (pre-jakarta) rather than mixing libraries"],"exampleFix":"// before\nengineConfig.setJpaEntityManagerFactory(hibernateSessionFactory); // wrong type\n// after\nEntityManagerFactory emf = LocalContainerEntityManagerFactoryBean.getObject();\nengineConfig.setJpaEntityManagerFactory(emf); // jakarta.persistence.EntityManagerFactory","handlingStrategy":"type-guard","validationCode":"if (!(candidate instanceof jakarta.persistence.EntityManagerFactory)) {\n    throw new IllegalArgumentException(\n        \"expected jakarta.persistence.EntityManagerFactory but got \" + candidate.getClass().getName());\n}","typeGuard":"boolean isJakartaEmf(Object o) {\n    return o instanceof jakarta.persistence.EntityManagerFactory;\n}","tryCatchPattern":"try {\n    config.setJpaEntityManagerFactory(candidate);\n} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {\n    if (e.getMessage().contains(\"EntityManagerFactory must implement\")) {\n        throw new IllegalStateException(\n            \"pass a jakarta.persistence.EntityManagerFactory (upgrade to Hibernate 5.5+/Spring Boot 3 if using javax)\", e);\n    }\n    throw e;\n}","preventionTips":["After migrating to Jakarta, check that your ORM (Hibernate 5.5+/6) implements jakarta.persistence interfaces","Never pass provider-native objects (e.g. Hibernate SessionFactory) where an EntityManagerFactory is required","Assert the injected bean type in Spring config before building the process engine"],"tags":["java","flowable","jpa","type-mismatch","jakarta"],"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"}