{"record":{"id":"cb28df105d05d5a5","repo":"hibernate/hibernate-orm","slug":"could-not-obtain-narayana-usertransaction-instance","errorCode":null,"errorMessage":"Could not obtain Narayana UserTransaction instance","messagePattern":"Could not obtain Narayana UserTransaction instance","errorType":"exception","errorClass":"JtaPlatformException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/NarayanaJtaPlatform.java","lineNumber":46,"sourceCode":"\t\t\t\t\t.getMethod( \"transactionManager\" )\n\t\t\t\t\t.invoke( null );\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new JtaPlatformException( \"Could not obtain Narayana TransactionManager instance\", e );\n\t\t}\n\t}\n\n\t@Override\n\tprotected UserTransaction locateUserTransaction() {\n\t\ttry {\n\t\t\treturn (UserTransaction) serviceRegistry()\n\t\t\t\t\t.requireService( ClassLoaderService.class )\n\t\t\t\t\t.classForName( UT_CLASS_NAME )\n\t\t\t\t\t.getMethod( \"userTransaction\" )\n\t\t\t\t\t.invoke( null );\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new JtaPlatformException( \"Could not obtain Narayana UserTransaction instance\", e );\n\t\t}\n\t}\n}\n","sourceCodeStart":28,"sourceCodeEnd":50,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/transaction/jta/platform/internal/NarayanaJtaPlatform.java#L28-L50","documentation":"NarayanaJtaPlatform.locateUserTransaction() reflectively invokes the static userTransaction() on com.arjuna.ats.jta.UserTransaction. JtaPlatformException('Could not obtain Narayana UserTransaction instance') indicates the Arjuna JTA facade is missing or uninitialized, so Hibernate cannot supply a UserTransaction for programmatic transaction demarcation.","triggerScenarios":"NarayanaJtaPlatform configured while com.arjuna.ats.jta.UserTransaction is not loadable; the UserTransaction is requested before Narayana initialized the transaction service; shading or classpath pruning dropping com.arjuna.ats.jta.*.","commonSituations":"Same family as the Narayana TM error: pruned dependencies, partially initialized Narayana in tests, mismatched versions after upgrades.","solutions":["Add org.jboss.narayana.jta:narayana-jta","Bootstrap Narayana before any Hibernate session usage","If you demarcate via Spring's JtaTransactionManager, make sure it resolves the UserTransaction itself and Hibernate's platform is consistent","Validate class presence at startup: Class.forName(\"com.arjuna.ats.jta.UserTransaction\")"],"exampleFix":"// before: JTA facade missing -> JtaPlatformException at first transaction\n// after (pom.xml):\n<dependency>\n    <groupId>org.jboss.narayana.jta</groupId>\n    <artifactId>narayana-jta</artifactId>\n    <version>7.0.2.Final</version>\n</dependency>","handlingStrategy":"validation","validationCode":"Class.forName(\"com.arjuna.ats.jta.UserTransaction\");\n// static accessor must return a UT instance\nClass.forName(\"com.arjuna.ats.jta.UserTransaction\").getMethod(\"userTransaction\").invoke(null);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the Narayana JTA facade complete (do not prune com.arjuna.ats.jta classes)","Initialize the Narayana transaction service before Hibernate needs a UserTransaction","Verify class visibility from Hibernate's classloader in shaded/embedded runtimes"],"tags":["jta","narayana","user-transaction","classpath"],"backgroundTag":"jta-platform-misconfiguration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}