{"record":{"id":"fe7b2e427f73328d","repo":"hibernate/hibernate-orm","slug":"illegal-attempt-to-specify-a-synchronizationtype-w","errorCode":null,"errorMessage":"Illegal attempt to specify a SynchronizationType when building an EntityManager from an EntityManagerFactory defined as RESOURCE_LOCAL (as opposed to JTA)","messagePattern":"Illegal attempt to specify a SynchronizationType when building an EntityManager from an EntityManagerFactory defined as RESOURCE_LOCAL \\(as opposed to JTA\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java","lineNumber":912,"sourceCode":"\tpublic Session createEntityManager(@Nullable Map<?,?> map) {\n\t\tvalidateNotClosed();\n\t\treturn buildEntityManager( SYNCHRONIZED, map );\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic Session createEntityManager(@Nonnull SynchronizationType synchronizationType) {\n\t\tvalidateNotClosed();\n\t\terrorIfResourceLocalDueToExplicitSynchronizationType();\n\t\treturn buildEntityManager( synchronizationType, null );\n\t}\n\n\tprivate void errorIfResourceLocalDueToExplicitSynchronizationType() {\n\t\t// JPA requires that we throw IllegalStateException in cases where:\n\t\t//\t\t1) the PersistenceUnitTransactionType (TransactionCoordinator) is non-JTA\n\t\t//\t\t2) an explicit SynchronizationType is specified\n\t\tif ( !transactionCoordinatorBuilder.isJta() ) {\n\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\"Illegal attempt to specify a SynchronizationType when building an EntityManager from an \" +\n\t\t\t\t\t\t\t\"EntityManagerFactory defined as RESOURCE_LOCAL (as opposed to JTA)\"\n\t\t\t);\n\t\t}\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic Session createEntityManager(@Nonnull SynchronizationType synchronizationType, @Nullable Map<?,?> map) {\n\t\tvalidateNotClosed();\n\t\terrorIfResourceLocalDueToExplicitSynchronizationType();\n\t\treturn buildEntityManager( synchronizationType, map );\n\t}\n\n\tprivate StatelessSession createEntityAgent() {\n\t\tvalidateNotClosed();\n\t\treturn statelessSessionBuilder( false ).openStatelessSession();\n\t}","sourceCodeStart":894,"sourceCodeEnd":930,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java#L894-L930","documentation":"JPA requires EntityManagerFactory.createEntityManager(SynchronizationType, ...) to throw IllegalStateException when the persistence unit is RESOURCE_LOCAL. Hibernate enforces this in errorIfResourceLocalDueToExplicitSynchronizationType(): a SynchronizationType argument only makes sense when container/JTA transaction synchronization drives the EntityManager. RESOURCE_LOCAL EntityManagers manage their own resource transactions and cannot be handed to the container for synchronization.","triggerScenarios":"Calling emf.createEntityManager(SynchronizationType.SYNCHRONIZED) or (SynchronizationType.UNSYNCHRONIZED, map) on a persistence unit whose transaction type is RESOURCE_LOCAL (set in persistence.xml or jakarta.persistence.transactionType=RESOURCE_LOCAL). Typical when code written for a JTA server (WildFly) is reused in Spring Boot/Java SE, which defaults to RESOURCE_LOCAL.","commonSituations":"Porting an EAR from WildFly to Spring Boot where the same createEntityManager(SynchronizationType) call remains; scaffolding code generated for JTA environments used with a local HikariCP+RESOURCE_LOCAL setup; libraries that always pass SynchronizationType.SYNCHRONIZED for Jakarta EE compatibility.","solutions":["Drop the SynchronizationType argument for RESOURCE_LOCAL units: call emf.createEntityManager() or createEntityManager(map) instead","If you truly need container-managed synchronized EMs, switch the persistence unit to JTA (jakarta.persistence.transactionType=JTA plus a JTA provider like Narayana/Atomikos)","Branch on the transaction type: read jakarta.persistence.transactionType from emf.getProperties() and choose the createEntityManager overload accordingly","In Spring, prefer injected EntityManager/@PersistenceContext or SharedEntityManagerCreator instead of manual factory calls"],"exampleFix":"// before\nEntityManager em = emf.createEntityManager(SynchronizationType.SYNCHRONIZED);\n// IllegalStateException: RESOURCE_LOCAL + explicit SynchronizationType\n\n// after (RESOURCE_LOCAL unit)\nEntityManager em = emf.createEntityManager();\nem.getTransaction().begin();\n// ...\nem.getTransaction().commit();\nem.close();","handlingStrategy":"validation","validationCode":"boolean isJta = \"JTA\".equalsIgnoreCase(\n        String.valueOf(emf.getProperties().get(\"jakarta.persistence.transactionType\")));\nEntityManager em = isJta\n        ? emf.createEntityManager(SynchronizationType.SYNCHRONIZED)\n        : emf.createEntityManager();","typeGuard":null,"tryCatchPattern":"try {\n    return emf.createEntityManager(SynchronizationType.SYNCHRONIZED);\n} catch (IllegalStateException e) {\n    // RESOURCE_LOCAL unit: retry without a SynchronizationType\n    return emf.createEntityManager();\n}","preventionTips":["Never hardcode a SynchronizationType in shared code — branch on the unit's transaction type","Keep container-managed patterns (JTA) and application-managed patterns (RESOURCE_LOCAL) in separate code paths","In Spring, prefer injected EntityManager so the container picks the correct creation mode"],"tags":["hibernate","jpa","transaction","resource-local","jta","synchronization"],"backgroundTag":"transaction-type-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}