11.7.7. Handle a Heuristic Outcome in a Transaction

This procedure shows how to handle a heuristic outcome in a JTA transaction, whether it is local or distributed, using the Java Transaction Service (JTS). To use distributed transactions, you need to configure the ORB. Refer to the ORB Configuration section of the Administration and Configuration Guide for more information on ORB configuration.
Heuristic transaction outcomes are uncommon and usually have exceptional causes. The word heuristic means "by hand", and that is the way that these outcomes usually have to be handled. Refer to Section 11.4.4, “About Heuristic Outcomes” for more information about heuristic transaction outcomes.

Procedure 11.5. Handle a heuristic outcome in a transaction

  1. Determine the cause

    The over-arching cause of a heuristic outcome in a transaction is that a resource manager promised it could commit or roll-back, and then failed to fulfill the promise. This could be due to a problem with a third-party component, the integration layer between the third-party component and JBoss EAP 6, or JBoss EAP 6 itself.
    By far, the most common two causes of heuristic errors are transient failures in the environment and coding errors in the code dealing with resource managers.
  2. Fix transient failures in the environment

    Typically, if there is a transient failure in your environment, you will know about it before you find out about the heuristic error. This could be a network outage, hardware failure, database failure, power outage, or a host of other things.
    If you experienced the heuristic outcome in a test environment, during stress testing, it provides information about weaknesses in your environment.


    JBoss EAP 6 will automatically recover transactions that were in a non-heuristic state at the time of the failure, but it does not attempt to recover heuristic transactions.
  3. Contact resource manager vendors

    If you have no obvious failure in your environment, or the heuristic outcome is easily reproducible, it is probably a coding error. Contact third-party vendors to find out if a solution is available. If you suspect the problem is in the transaction manager of JBoss EAP 6 itself, contact Red Hat Global Support Services.
  4. In a test environment, delete the logs and restart JBoss EAP 6.

    In a test environment, or if you do not care about the integrity of the data, deleting the transaction logs and restarting JBoss EAP 6 gets rid of the heuristic outcome. The transaction logs are located in EAP_HOME/standalone/data/tx-object-store/ for a standalone server, or EAP_HOME/domain/servers/SERVER_NAME/data/tx-object-store in a managed domain, by default. In the case of a managed domain, SERVER_NAME refers to the name of the individual server participating in a server group.


    The location of the transaction log also depends on the object store in use and the values set for the oject-store-relative-to and object-store-path parameters. For file system logs (such as a standard shadow and HornetQ logs) the default direction location is used, but when using a JDBC object store, the transaction logs are stored in a database.
  5. Resolve the outcome by hand

    The process of resolving the transaction outcome by hand is very dependent on the exact circumstance of the failure. Typically, you need to take the following steps, applying them to your situation:
    1. Identify which resource managers were involved.
    2. Examine the state in the transaction manager and the resource managers.
    3. Manually force log cleanup and data reconciliation in one or more of the involved components.
    The details of how to perform these steps are out of the scope of this documentation.