hibernate/hibernate-orm · critical · JndiException

unable to find UserTransaction

Error message

unable to find UserTransaction

What it means

The same JBoss app-server platform resolving the UserTransaction: locateUserTransaction() tries java:jboss/UserTransaction, falls back to java:comp/UserTransaction, and throws JndiException('unable to find UserTransaction') when neither name is bound. Even if the TransactionManager was found, transaction demarcation through a UserTransaction then fails.

Source

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

				return (TransactionManager) jndiService().locate( AS4_TM_NAME );
			}
			catch (JndiException jndiExceptionInner) {
				throw new JndiException( "unable to find transaction manager", jndiException );
			}
		}
	}

	@Override
	protected UserTransaction locateUserTransaction() {
		try {
			return (UserTransaction) jndiService().locate( JBOSS_UT_NAME );
		}
		catch (JndiException jndiException) {
			try {
				return (UserTransaction) jndiService().locate( UT_NAME );
			}
			catch (JndiException jndiExceptionInner) {
				throw new JndiException( "unable to find UserTransaction", jndiException );
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use a standalone JTA platform (JBossStandAloneJtaPlatform/NarayanaJtaPlatform) when not deployed in JBoss/WildFly
2. In a web module, declare a resource-ref for java:comp/UserTransaction or use the app-server-wide name
3. Prefer obtaining the UserTransaction from the configured JtaPlatform or the container rather than raw JNDI
4. Verify both JNDI names resolve in the target server before enabling this platform

Example fix

// before: web module has no environment entry
new InitialContext().lookup("java:comp/UserTransaction"); // NamingException -> unable to find UserTransaction

// after (web.xml): declare the reference
<web-app>
  <resource-ref>
    <res-ref-name>UserTransaction</res-ref-name>
    <res-type>javax.transaction.UserTransaction</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
</web-app>

new javax.naming.InitialContext().lookup("java:jboss/UserTransaction");
// fallback check: new InitialContext().lookup("java:comp/UserTransaction");

When it happens

Trigger: JTA platform set to JBossAppServerJtaPlatform in a non-JBoss environment; java:comp/UserTransaction not linked in a web module (missing resource-ref); naming restrictions preventing the fallback lookup from resolving.

Common situations: Standalone Spring/Narayana runs inheriting a WildFly configuration; WARs or batch tools where the java:comp environment is not set up; platform auto-detection picking the app-server platform because JBoss classes are on the classpath while JBoss JNDI is not.

Related errors

• unable to find transaction manager
• Could not obtain JBoss Transactions user transaction instanc
• UserTransaction reported transaction status as unknown
• Could not determine transaction status
• Could not obtain JBoss Transactions transaction manager inst

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