{"record":{"id":"1f39a0de3c6902cd","repo":"hibernate/hibernate-orm","slug":"unable-to-find-usertransaction","errorCode":null,"errorMessage":"unable to find UserTransaction","messagePattern":"unable to find UserTransaction","errorType":"exception","errorClass":"JndiException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/JBossAppServerJtaPlatform.java","lineNumber":53,"sourceCode":"\t\t\t\treturn (TransactionManager) jndiService().locate( AS4_TM_NAME );\n\t\t\t}\n\t\t\tcatch (JndiException jndiExceptionInner) {\n\t\t\t\tthrow new JndiException( \"unable to find transaction manager\", jndiException );\n\t\t\t}\n\t\t}\n\t}\n\n\t@Override\n\tprotected UserTransaction locateUserTransaction() {\n\t\ttry {\n\t\t\treturn (UserTransaction) jndiService().locate( JBOSS_UT_NAME );\n\t\t}\n\t\tcatch (JndiException jndiException) {\n\t\t\ttry {\n\t\t\t\treturn (UserTransaction) jndiService().locate( UT_NAME );\n\t\t\t}\n\t\t\tcatch (JndiException jndiExceptionInner) {\n\t\t\t\tthrow new JndiException( \"unable to find UserTransaction\", jndiException );\n\t\t\t}\n\t\t}\n\t}\n}\n","sourceCodeStart":35,"sourceCodeEnd":58,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/JBossAppServerJtaPlatform.java#L35-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a standalone JTA platform (JBossStandAloneJtaPlatform/NarayanaJtaPlatform) when not deployed in JBoss/WildFly","In a web module, declare a resource-ref for java:comp/UserTransaction or use the app-server-wide name","Prefer obtaining the UserTransaction from the configured JtaPlatform or the container rather than raw JNDI","Verify both JNDI names resolve in the target server before enabling this platform"],"exampleFix":"// before: web module has no environment entry\nnew InitialContext().lookup(\"java:comp/UserTransaction\"); // NamingException -> unable to find UserTransaction\n\n// after (web.xml): declare the reference\n<web-app>\n  <resource-ref>\n    <res-ref-name>UserTransaction</res-ref-name>\n    <res-type>javax.transaction.UserTransaction</res-type>\n    <res-auth>Container</res-auth>\n  </resource-ref>\n</web-app>","handlingStrategy":"validation","validationCode":"new javax.naming.InitialContext().lookup(\"java:jboss/UserTransaction\");\n// fallback check: new InitialContext().lookup(\"java:comp/UserTransaction\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Declare a resource-ref for java:comp/UserTransaction in web modules that need it","Use standalone JTA platforms outside JBoss/WildFly","Validate both JNDI names at startup before enabling the platform","Prefer container-injected UserTransaction over manual JNDI lookups"],"tags":["jta","jndi","jboss","user-transaction"],"backgroundTag":"jndi-lookup-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}