{"record":{"id":"7a6612f51a73d5b3","repo":"hibernate/hibernate-orm","slug":"could-not-instantiate-atomikos-transactionmanager","errorCode":null,"errorMessage":"Could not instantiate Atomikos TransactionManager","messagePattern":"Could not instantiate Atomikos TransactionManager","errorType":"exception","errorClass":"JtaPlatformException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/AtomikosJtaPlatform.java","lineNumber":28,"sourceCode":"import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;\nimport org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformException;\n\n/**\n * @author Vlad Mihalcea\n */\npublic class AtomikosJtaPlatform extends AbstractJtaPlatform {\n\tpublic static final String TM_CLASS_NAME = \"com.atomikos.icatch.jta.UserTransactionManager\";\n\n\t@Override\n\tprotected TransactionManager locateTransactionManager() {\n\t\ttry {\n\t\t\treturn (TransactionManager) serviceRegistry()\n\t\t\t\t\t.requireService( ClassLoaderService.class )\n\t\t\t\t\t.classForName( TM_CLASS_NAME )\n\t\t\t\t\t.newInstance();\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new JtaPlatformException( \"Could not instantiate Atomikos TransactionManager\", e );\n\t\t}\n\t}\n\n\t@Override\n\tprotected UserTransaction locateUserTransaction() {\n\t\treturn (UserTransaction) jndiService().locate( \"java:comp/UserTransaction\" );\n\t}\n}\n","sourceCodeStart":10,"sourceCodeEnd":37,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/AtomikosJtaPlatform.java#L10-L37","documentation":"AtomikosJtaPlatform.locateTransactionManager() reflectively loads com.atomikos.icatch.jta.UserTransactionManager through Hibernate's ClassLoaderService and calls newInstance(). JtaPlatformException('Could not instantiate Atomikos TransactionManager') means the class is missing from the classpath, invisible to Hibernate's classloader, or its constructor threw — Atomikos 5.x/6.x requires valid transactions.properties/jta.properties before a UserTransactionManager can be constructed.","triggerScenarios":"hibernate.transaction.jta.platform resolving to AtomikosJtaPlatform while com.atomikos:transactions-jta is absent; Atomikos sitting in a classloader Hibernate cannot see; constructor failure from missing or invalid Atomikos configuration on 5.x+; mixed com.atomikos artifact versions.","commonSituations":"Spring Boot app adding Hibernate JTA support without atomikos-spring-boot-starter or transactions-jta; upgrading Atomikos 4.0.6 to 5.x/6.x where bootstrap configuration became mandatory; fat-jar or shaded deployments reordering classloaders.","solutions":["Add com.atomikos:transactions-jta (with transactions-api) at the same version as the rest of your Atomikos artifacts","Provide a valid transactions.properties/jta.properties so new UserTransactionManager() succeeds","Pin one known-good Atomikos version consistently across all com.atomikos artifacts","If JTA is not actually used, remove the JTA platform setting so Hibernate does not auto-detect Atomikos"],"exampleFix":"// before (pom.xml): Atomikos classes missing -> JtaPlatformException at first transaction\n// after (pom.xml):\n<dependency>\n    <groupId>com.atomikos</groupId>\n    <artifactId>transactions-jta</artifactId>\n    <version>6.0.0</version>\n</dependency>\n<dependency>\n    <groupId>com.atomikos</groupId>\n    <artifactId>transactions-api</artifactId>\n    <version>6.0.0</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// fail fast at startup: the exact class AtomikosJtaPlatform instantiates\nClass.forName(\"com.atomikos.icatch.jta.UserTransactionManager\")\n     .getDeclaredConstructor().newInstance();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin one consistent Atomikos version across all com.atomikos artifacts","Set hibernate.transaction.jta.platform explicitly instead of relying on auto-detection","Add a CI smoke test that builds the SessionFactory with the production classpath","Provide transactions.properties so the Atomikos constructor cannot fail on configuration"],"tags":["atomikos","jta","classpath","transaction-manager"],"backgroundTag":"jta-platform-misconfiguration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}