flowable/flowable-engine · error · ActivitiException

SystemException while registering synchronization

Error message

SystemException while registering synchronization

What it means

addTransactionListener() wraps javax.transaction.SystemException from Transaction.registerSynchronization() in this ActivitiException. SystemException means the JTA transaction manager failed internally while attempting to register the synchronization — an infrastructure-level failure, not a state or usage problem.

Solutions

  1. Read the chained SystemException cause and the app-server transaction logs for the root failure.
  2. Verify XA datasource and transaction recovery manager configuration.
  3. Upgrade the app server / JTA provider — some SystemException cases are fixed provider bugs.
  4. Retry the command once the transaction service is healthy; escalate to infrastructure if persistent.
Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: ensure the JTA provider responds
transactionManager.getStatus();

Try / catch

try { ctx.addTransactionListener(state, listener); } catch (ActivitiException e) { if (e.getCause() instanceof SystemException) { alertOps("JTA provider failure during synchronization registration"); } else { throw e; } }

Prevention

When it happens

Trigger: Calling addTransactionListener when the JTA transaction manager or its resources are malfunctioning — transaction service error, resource adapter failure, or recoverable internal error.

Common situations: App-server transaction service instability; XA resource failures mid-transaction; engine running against a JTA implementation with known bugs (older JBossTS versions).

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/824c3a14a390eea3. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/jta/JtaTransactionContext.java:81

        try {
            return transactionManager.getTransaction();
        } catch (SystemException e) {
            throw new ActivitiException("SystemException while getting transaction ", e);
        }
    }

    @Override
    public void addTransactionListener(TransactionState transactionState, final TransactionListener transactionListener) {
        Transaction transaction = getTransaction();
        CommandContext commandContext = Context.getCommandContext();
        try {
            transaction.registerSynchronization(new TransactionStateSynchronization(transactionState, transactionListener, commandContext));
        } catch (IllegalStateException e) {
            throw new ActivitiException("IllegalStateException while registering synchronization ", e);
        } catch (RollbackException e) {
            throw new ActivitiException("RollbackException while registering synchronization ", e);
        } catch (SystemException e) {
            throw new ActivitiException("SystemException while registering synchronization ", e);
        }
    }

    public static class TransactionStateSynchronization implements Synchronization {

        protected final TransactionListener transactionListener;
        protected final TransactionState transactionState;
        private final CommandContext commandContext;

        public TransactionStateSynchronization(TransactionState transactionState, TransactionListener transactionListener, CommandContext commandContext) {
            this.transactionState = transactionState;
            this.transactionListener = transactionListener;
            this.commandContext = commandContext;
        }

        @Override
        public void beforeCompletion() {
            if (TransactionState.COMMITTING == transactionState

View on GitHub (pinned to d6d39ce1c6)