{"record":{"id":"78c5a34f0f575a82","repo":"hibernate/hibernate-orm","slug":"unable-to-access-transactionmanager-or-usertransac","errorCode":null,"errorMessage":"Unable to access TransactionManager or UserTransaction to make physical transaction delegate","messagePattern":"Unable to access TransactionManager or UserTransaction to make physical transaction delegate","errorType":"exception","errorClass":"JtaPlatformInaccessibleException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jta/internal/JtaTransactionCoordinatorImpl.java","lineNumber":223,"sourceCode":"\t}\n\n\t@Override\n\t@Nonnull\n\tpublic TransactionDriver getTransactionDriverControl() {\n\t\tif ( physicalTransactionDelegate == null ) {\n\t\t\tphysicalTransactionDelegate = makePhysicalTransactionDelegate();\n\t\t}\n\t\treturn physicalTransactionDelegate;\n\t}\n\n\t@Nonnull\n\tprivate TransactionDriverControlImpl makePhysicalTransactionDelegate() {\n\t\tfinal var adapter =\n\t\t\t\tpreferUserTransactions\n\t\t\t\t\t\t? getTransactionAdapterPreferringUserTransaction()\n\t\t\t\t\t\t: getTransactionAdapterPreferringTransactionManager();\n\t\tif ( adapter == null ) {\n\t\t\tthrow new JtaPlatformInaccessibleException(\n\t\t\t\t\t\"Unable to access TransactionManager or UserTransaction to make physical transaction delegate\"\n\t\t\t);\n\t\t}\n\t\telse {\n\t\t\treturn new TransactionDriverControlImpl( adapter );\n\t\t}\n\t}\n\n\t@Nullable\n\tprivate JtaTransactionAdapter getTransactionAdapterPreferringTransactionManager() {\n\t\tfinal var adapter = makeTransactionManagerAdapter();\n\t\tif ( adapter == null ) {\n\t\t\tJTA_LOGGER.unableToAccessTransactionManagerTryingUserTransaction();\n\t\t\treturn makeUserTransactionAdapter();\n\t\t}\n\t\telse {\n\t\t\treturn adapter;\n\t\t}","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jta/internal/JtaTransactionCoordinatorImpl.java#L205-L241","documentation":"The coordinator builds its physical transaction delegate lazily by asking the configured JtaPlatform for a TransactionManager (or UserTransaction when preferUserTransactions); when the retrieval returns null it throws JtaPlatformInaccessibleException. The JtaPlatform class itself resolved, but its lookups (usually JNDI) failed, so Hibernate has no handle to drive transactions. It fires on the first transactional operation of a JTA-configured SessionFactory.","triggerScenarios":"Bootstrap with coordinator_class=jta (or a jta-data-source) in an environment where JtaPlatform.retrieveTransactionManager()/retrieveUserTransaction() return null: wrong or missing hibernate.transaction.jta.platform, JNDI names not bound (plain Java SE with no TM), or an unrecognized container whose JNDI names the bundled platform does not know.","commonSituations":"Java SE bootstrap with the jta coordinator but no transaction manager; deploying to an app server version with changed JNDI names; a typo in the jta.platform setting; test harnesses without a JTA provider.","solutions":["Set the platform explicitly, e.g. hibernate.transaction.jta.platform=org.hibernate.engine.transaction.jta.platform.internal.JBossStandAloneJtaPlatform (with Narayana) or the class matching your container","Or stop needing JTA: use a resource-local setup (non-JTA DataSource, JDBC coordinator) when no transaction manager exists","Verify the expected JNDI bindings for your platform exist (java:/TransactionManager, java:jboss/TransactionManager, java:comp/UserTransaction, ...)","Upgrade Hibernate - newer versions auto-detect more containers"],"exampleFix":"// before (Java SE: no platform detected, first tx fails)\nMap<String, Object> cfg = Map.of(\n    \"hibernate.transaction.coordinator_class\", \"jta\");\n\n// after (Narayana on the classpath)\nMap<String, Object> cfg = Map.of(\n    \"hibernate.transaction.coordinator_class\", \"jta\",\n    \"hibernate.transaction.jta.platform\",\n        \"org.hibernate.engine.transaction.jta.platform.internal.JBossStandAloneJtaPlatform\");","handlingStrategy":"validation","validationCode":"// Fail fast at startup instead of on first transaction use\ntry {\n    Object tm = new InitialContext().lookup(\"java:/TransactionManager\"); // adjust name per platform\n    if ( tm == null ) {\n        throw new IllegalStateException(\"Set hibernate.transaction.jta.platform explicitly\");\n    }\n}\ncatch (NamingException e) {\n    throw new IllegalStateException(\"No JTA TransactionManager bound; do not use coordinator_class=jta\", e);\n}","typeGuard":"static boolean canRetrieveJtaTransactionManager(JtaPlatform platform) {\n    return platform != null && platform.retrieveTransactionManager() != null;\n}","tryCatchPattern":"try {\n    session.beginTransaction();\n}\ncatch (JtaPlatformInaccessibleException e) {\n    // configuration error, not transient: fix hibernate.transaction.jta.platform / JNDI and rebuild\n    throw new IllegalStateException(\"JTA platform misconfigured\", e);\n}","preventionTips":["Set hibernate.transaction.jta.platform explicitly in SE and unusual containers","Use resource-local (JDBC) transactions when no transaction manager exists","Add a startup smoke test that opens a session and begins/rolls back a transaction"],"tags":["jta","hibernate","configuration","jndi","bootstrap","java-se"],"backgroundTag":"jta-platform-unavailable","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}