hibernate/hibernate-orm · critical · JtaPlatformException

Could not obtain WildFly Transaction Client transaction mana

Error message

Could not obtain WildFly Transaction Client transaction manager instance

What it means

WildFlyStandAloneJtaPlatform.locateTransactionManager() reflectively calls getInstance() on org.wildfly.transaction.client.ContextTransactionManager. JtaPlatformException('Could not obtain WildFly Transaction Client transaction manager instance') means the wildfly-transaction-client library is missing or not visible, so the standalone WildFly transaction manager cannot be obtained.

Source

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

 * Known to work for WildFly 13+
 *
 * @author Scott Marlow
 */
public class WildFlyStandAloneJtaPlatform extends AbstractJtaPlatform {
	public static final String WILDFLY_TM_CLASS_NAME = "org.wildfly.transaction.client.ContextTransactionManager";
	public static final String WILDFLY_UT_CLASS_NAME = "org.wildfly.transaction.client.LocalUserTransaction";

	@Override
	protected TransactionManager locateTransactionManager() {
		try {
			return (TransactionManager) serviceRegistry()
					.requireService( ClassLoaderService.class )
					.classForName( WILDFLY_TM_CLASS_NAME )
					.getMethod( "getInstance" )
					.invoke( null );
		}
		catch (Exception e) {
			throw new JtaPlatformException(
					"Could not obtain WildFly Transaction Client transaction manager instance",
					e
			);
		}
	}

	@Override
	protected UserTransaction locateUserTransaction() {
		try {
			return (UserTransaction) serviceRegistry()
					.requireService( ClassLoaderService.class )
					.classForName( WILDFLY_UT_CLASS_NAME ).getMethod( "getInstance" ).invoke( null );
		}
		catch (Exception e) {
			throw new JtaPlatformException(
					"Could not obtain WildFly Transaction Client user transaction instance",
					e
			);

View on GitHub (pinned to fad1729dce)

Solutions

1. Add org.wildfly.transaction.client:wildfly-transaction-client to the runtime classpath
2. Match the client version to the Narayana version in use (use the pair shipped with your WildFly)
3. If plain Narayana suffices, switch to NarayanaJtaPlatform instead
4. Smoke-test Class.forName("org.wildfly.transaction.client.ContextTransactionManager") at startup

Example fix

// before (pom.xml): client jar missing
// after (pom.xml):
<dependency>
    <groupId>org.wildfly.transaction.client</groupId>
    <artifactId>wildfly-transaction-client</artifactId>
    <version>2.0.1.Final</version>
</dependency>

Class.forName("org.wildfly.transaction.client.ContextTransactionManager");
// present only when wildfly-transaction-client is on the runtime classpath

When it happens

Trigger: hibernate.transaction.jta.platform=WildFlyStandAloneJtaPlatform without org.wildfly.transaction.client:wildfly-transaction-client on the classpath; shaded jars stripping the client classes; a version mismatch where getInstance() throws.

Common situations: Spring Boot apps wanting the WildFly transaction client for standalone XA but forgetting the dependency; dependency conflicts between wildfly-transaction-client and an embedded Narayana.

Related errors

• Could not instantiate Atomikos TransactionManager
• unable to find transaction manager
• Could not obtain JBoss Transactions transaction manager inst
• Could not obtain Narayana TransactionManager instance
• Could not obtain WebSphere Liberty transaction manager insta

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