{"record":{"id":"46a1a495f64824d2","repo":"hibernate/hibernate-orm","slug":"jta-usertransaction-begin-failed","errorCode":null,"errorMessage":"JTA UserTransaction.begin() failed","messagePattern":"JTA UserTransaction\\.begin\\(\\) failed","errorType":"exception","errorClass":"TransactionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jta/internal/JtaTransactionAdapterUserTransactionImpl.java","lineNumber":46,"sourceCode":"\tpublic JtaTransactionAdapterUserTransactionImpl(@Nonnull UserTransaction userTransaction) {\n\t\tthis.userTransaction = userTransaction;\n\t}\n\n\t@Override\n\tpublic void begin() {\n\t\ttry {\n\t\t\tif ( getStatus() == TransactionStatus.NOT_ACTIVE ) {\n\t\t\t\tJTA_LOGGER.callingUserTransactionBegin();\n\t\t\t\tuserTransaction.begin();\n\t\t\t\tinitiator = true;\n\t\t\t\tJTA_LOGGER.calledUserTransactionBegin();\n\t\t\t}\n\t\t\telse {\n\t\t\t\tJTA_LOGGER.skippingTransactionManagerBegin();\n\t\t\t}\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new TransactionException( \"JTA UserTransaction.begin() failed\", e );\n\t\t}\n\t}\n\n\t@Override\n\tpublic void commit() {\n\t\ttry {\n\t\t\tif ( initiator ) {\n\t\t\t\tinitiator = false;\n\t\t\t\tJTA_LOGGER.callingUserTransactionCommit();\n\t\t\t\tuserTransaction.commit();\n\t\t\t\tJTA_LOGGER.calledUserTransactionCommit();\n\t\t\t}\n\t\t\telse {\n\t\t\t\tJTA_LOGGER.skippingTransactionManagerCommit();\n\t\t\t}\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new TransactionException( \"JTA UserTransaction.commit() failed\", e );","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/resource/transaction/backend/jta/internal/JtaTransactionAdapterUserTransactionImpl.java#L28-L64","documentation":"The UserTransaction-based JTA adapter's begin(): it calls UserTransaction.begin() when it just observed status NOT_ACTIVE and wraps any exception in this TransactionException. UserTransaction is the application-facing JTA handle; the wrapped exception (NotSupportedException/SystemException/IllegalStateException) means the UT refused to start a transaction - commonly because a transaction is already associated with the thread or the UT is unusable in the current context.","triggerScenarios":"Transaction.begin() on a session whose coordinator prefers UserTransactions (preferUserTransactions) when UserTransaction.begin() throws: a container-managed transaction already active on the thread (raced status check), the container forbidding user transactions on that thread, or the UT not bound/usable.","commonSituations":"Calling beginTransaction() during a container-managed transaction; a UserTransaction JNDI binding valid only inside EE components; invoking from unmanaged threads; SE setups with no bound UserTransaction.","solutions":["Check UserTransaction.getStatus() before beginning; only begin when no transaction is active","Drop the preferUserTransactions setting so the coordinator drives the TransactionManager instead","Verify the JNDI name / JtaPlatform used to obtain the UserTransaction","Use container-managed transaction demarcation in EE environments"],"exampleFix":"// before\nUserTransaction ut = ...;\nut.begin(); // inside an already-active container-managed tx\n\n// after\nif ( ut.getStatus() == jakarta.transaction.Status.STATUS_NO_TRANSACTION ) {\n    ut.begin();\n}","handlingStrategy":"validation","validationCode":"// Only begin via UserTransaction when none is active\nif ( ut.getStatus() == jakarta.transaction.Status.STATUS_NO_TRANSACTION ) {\n    ut.begin();\n}\nelse {\n    throw new IllegalStateException(\"A JTA transaction is already active\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    session.beginTransaction();\n}\ncatch (TransactionException e) {\n    Throwable c = e.getCause();\n    if ( c instanceof IllegalStateException || c instanceof NotSupportedException ) {\n        // UserTransaction refused: a tx is already associated or UT unusable here\n    }\n    throw e;\n}","preventionTips":["Do not begin transactions on threads already carrying a container-managed JTA transaction","In SE, prefer the TransactionManager-based coordinator over preferUserTransactions","Verify the UserTransaction JNDI binding is valid for the calling context"],"tags":["jta","transactions","hibernate","usertransaction","begin"],"backgroundTag":"transaction-begin-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}