{"record":{"id":"0ca51d4c9b19d36b","repo":"hibernate/hibernate-orm","slug":"usertransaction-reported-transaction-status-as-unk","errorCode":null,"errorMessage":"UserTransaction reported transaction status as unknown","messagePattern":"UserTransaction reported transaction status as unknown","errorType":"exception","errorClass":"TransactionException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/engine/transaction/internal/jta/JtaStatusHelper.java","lineNumber":42,"sourceCode":" */\npublic final class JtaStatusHelper {\n\tprivate JtaStatusHelper() {\n\t}\n\n\t/**\n\t * Extract the status code from a {@link UserTransaction}\n\t *\n\t * @param userTransaction The {@link UserTransaction} from which to extract the status.\n\t *\n\t * @return The transaction status\n\t *\n\t * @throws TransactionException If the {@link UserTransaction} reports the status as unknown\n\t */\n\tpublic static int getStatus(UserTransaction userTransaction) {\n\t\ttry {\n\t\t\tfinal int status = userTransaction.getStatus();\n\t\t\tif ( status == STATUS_UNKNOWN ) {\n\t\t\t\tthrow new TransactionException( \"UserTransaction reported transaction status as unknown\" );\n\t\t\t}\n\t\t\treturn status;\n\t\t}\n\t\tcatch ( SystemException se ) {\n\t\t\tthrow new TransactionException( \"Could not determine transaction status\", se );\n\t\t}\n\t}\n\n\t/**\n\t * Extract the status code from the current {@link jakarta.transaction.Transaction} associated with the\n\t * given {@link TransactionManager}\n\t *\n\t * @param transactionManager The {@link TransactionManager} from which to extract the status.\n\t *\n\t * @return The transaction status\n\t *\n\t * @throws TransactionException If the {@link TransactionManager} reports the status as unknown\n\t */","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/transaction/internal/jta/JtaStatusHelper.java#L24-L60","documentation":"JtaStatusHelper.getStatus(UserTransaction) reads the JTA status code to decide whether a transaction exists and can be joined. javax.transaction.Status.STATUS_UNKNOWN means the transaction's outcome cannot be determined (e.g. a resource failure left it in limbo), and Hibernate refuses to make decisions on it, throwing TransactionException('UserTransaction reported transaction status as unknown').","triggerScenarios":"Any Hibernate path that inspects the current transaction through a UserTransaction (transaction coordinator checks, session/JTA interplay) while the JTA implementation returns STATUS_UNKNOWN — typically during or after transaction manager recovery, after an XA resource failure, or after a timeout that left the transaction in-doubt.","commonSituations":"Narayana/Atomikos recovery in progress after a crash or resource drop; an XA datasource that failed mid-commit; transaction manager under stress or restarting; heavyweight in-doubt transactions from a database outage.","solutions":["Check the transaction manager and resource logs; let recovery complete before retrying the operation","Fix the underlying XA resource failure (database/XAResource availability) that left the transaction unknown","Retry the work on a fresh transaction once UserTransaction.getStatus() reports a stable, known status","Verify hibernate.transaction.jta.platform resolves the transaction manager your application actually uses"],"exampleFix":"// before\nnew SessionImpl(...); // opening/using a session while UserTransaction status is STATUS_UNKNOWN\n\n// after\nint s = userTransaction.getStatus();\nif (s == Status.STATUS_UNKNOWN) {\n    // wait for JTA recovery, then start a new transaction\n    throw new TransactionRetryableException(\"JTA status unknown; retry after recovery\");\n}\n// proceed with session/transaction work","handlingStrategy":"retry","validationCode":"int status = userTransaction.getStatus();\nif (status == javax.transaction.Status.STATUS_UNKNOWN) {\n    // defer work until the JTA manager reports a stable status\n    throw new IllegalStateException(\"JTA transaction status unknown; retry after recovery\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // session/transaction work that inspects JTA status\n} catch (org.hibernate.TransactionException e) {\n    if (\"UserTransaction reported transaction status as unknown\".equals(e.getMessage())) {\n        // back off, let the TM finish recovery, then retry on a new transaction\n        scheduleRetry();\n    } else {\n        throw e;\n    }\n}","preventionTips":["Monitor transaction-manager health and XA resource availability (unknown status usually follows resource failure)","Verify hibernate.transaction.jta.platform matches your runtime TM","Avoid using sessions while recovery is in progress; probe UserTransaction.getStatus() first"],"tags":["hibernate","jta","user-transaction","status-unknown","transaction-manager"],"backgroundTag":"jta-status-unknown","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}