hibernate/hibernate-orm · critical · JtaPlatformException

Could not instantiate Atomikos TransactionManager

Error message

Could not instantiate Atomikos TransactionManager

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/AtomikosJtaPlatform.java:28

import org.hibernate.boot.registry.classloading.spi.ClassLoaderService;
import org.hibernate.engine.transaction.jta.platform.spi.JtaPlatformException;

/**
 * @author Vlad Mihalcea
 */
public class AtomikosJtaPlatform extends AbstractJtaPlatform {
	public static final String TM_CLASS_NAME = "com.atomikos.icatch.jta.UserTransactionManager";

	@Override
	protected TransactionManager locateTransactionManager() {
		try {
			return (TransactionManager) serviceRegistry()
					.requireService( ClassLoaderService.class )
					.classForName( TM_CLASS_NAME )
					.newInstance();
		}
		catch (Exception e) {
			throw new JtaPlatformException( "Could not instantiate Atomikos TransactionManager", e );
		}
	}

	@Override
	protected UserTransaction locateUserTransaction() {
		return (UserTransaction) jndiService().locate( "java:comp/UserTransaction" );
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Add com.atomikos:transactions-jta (with transactions-api) at the same version as the rest of your Atomikos artifacts
2. Provide a valid transactions.properties/jta.properties so new UserTransactionManager() succeeds
3. Pin one known-good Atomikos version consistently across all com.atomikos artifacts
4. If JTA is not actually used, remove the JTA platform setting so Hibernate does not auto-detect Atomikos

Example fix

// before (pom.xml): Atomikos classes missing -> JtaPlatformException at first transaction
// after (pom.xml):
<dependency>
    <groupId>com.atomikos</groupId>
    <artifactId>transactions-jta</artifactId>
    <version>6.0.0</version>
</dependency>
<dependency>
    <groupId>com.atomikos</groupId>
    <artifactId>transactions-api</artifactId>
    <version>6.0.0</version>
</dependency>

// fail fast at startup: the exact class AtomikosJtaPlatform instantiates
Class.forName("com.atomikos.icatch.jta.UserTransactionManager")
     .getDeclaredConstructor().newInstance();

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not obtain JBoss Transactions transaction manager inst
• Could not obtain Narayana TransactionManager instance
• Could not obtain WebSphere Liberty transaction manager insta
• Could not obtain WildFly Transaction Client transaction mana
• Could not obtain TransactionManager from JtaPlatform

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/7a6612f51a73d5b3. Report an issue: GitHub.