hibernate/hibernate-orm · error · TransactionException

UserTransaction reported transaction status as unknown

Error message

UserTransaction reported transaction status as unknown

What it means

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').

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/transaction/internal/jta/JtaStatusHelper.java:42

 */
public final class JtaStatusHelper {
	private JtaStatusHelper() {
	}

	/**
	 * Extract the status code from a {@link UserTransaction}
	 *
	 * @param userTransaction The {@link UserTransaction} from which to extract the status.
	 *
	 * @return The transaction status
	 *
	 * @throws TransactionException If the {@link UserTransaction} reports the status as unknown
	 */
	public static int getStatus(UserTransaction userTransaction) {
		try {
			final int status = userTransaction.getStatus();
			if ( status == STATUS_UNKNOWN ) {
				throw new TransactionException( "UserTransaction reported transaction status as unknown" );
			}
			return status;
		}
		catch ( SystemException se ) {
			throw new TransactionException( "Could not determine transaction status", se );
		}
	}

	/**
	 * Extract the status code from the current {@link jakarta.transaction.Transaction} associated with the
	 * given {@link TransactionManager}
	 *
	 * @param transactionManager The {@link TransactionManager} from which to extract the status.
	 *
	 * @return The transaction status
	 *
	 * @throws TransactionException If the {@link TransactionManager} reports the status as unknown
	 */

View on GitHub (pinned to fad1729dce)

Solutions

1. Check the transaction manager and resource logs; let recovery complete before retrying the operation
2. Fix the underlying XA resource failure (database/XAResource availability) that left the transaction unknown
3. Retry the work on a fresh transaction once UserTransaction.getStatus() reports a stable, known status
4. Verify hibernate.transaction.jta.platform resolves the transaction manager your application actually uses

Example fix

// before
new SessionImpl(...); // opening/using a session while UserTransaction status is STATUS_UNKNOWN

// after
int s = userTransaction.getStatus();
if (s == Status.STATUS_UNKNOWN) {
    // wait for JTA recovery, then start a new transaction
    throw new TransactionRetryableException("JTA status unknown; retry after recovery");
}
// proceed with session/transaction work

int status = userTransaction.getStatus();
if (status == javax.transaction.Status.STATUS_UNKNOWN) {
    // defer work until the JTA manager reports a stable status
    throw new IllegalStateException("JTA transaction status unknown; retry after recovery");
}

try {
    // session/transaction work that inspects JTA status
} catch (org.hibernate.TransactionException e) {
    if ("UserTransaction reported transaction status as unknown".equals(e.getMessage())) {
        // back off, let the TM finish recovery, then retry on a new transaction
        scheduleRetry();
    } else {
        throw e;
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not determine transaction status
• TransactionManager reported transaction status as unknwon
• Could not obtain TransactionManager from JtaPlatform
• Problem locating/validating JTA transaction
• DdlTransactionIsolatorJtaImpl could not locate TransactionMa

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/0ca51d4c9b19d36b. Report an issue: GitHub.