11.7.7. Handle a Heuristic Outcome in a Transaction

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.

   Warning

   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.

   Note

   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.