{"record":{"id":"824c3a14a390eea3","repo":"flowable/flowable-engine","slug":"systemexception-while-registering-synchronization-824c3a","errorCode":null,"errorMessage":"SystemException while registering synchronization ","messagePattern":"SystemException while registering synchronization ","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/jta/JtaTransactionContext.java","lineNumber":81,"sourceCode":"        try {\r\n            return transactionManager.getTransaction();\r\n        } catch (SystemException e) {\r\n            throw new ActivitiException(\"SystemException while getting transaction \", e);\r\n        }\r\n    }\r\n\r\n    @Override\r\n    public void addTransactionListener(TransactionState transactionState, final TransactionListener transactionListener) {\r\n        Transaction transaction = getTransaction();\r\n        CommandContext commandContext = Context.getCommandContext();\r\n        try {\r\n            transaction.registerSynchronization(new TransactionStateSynchronization(transactionState, transactionListener, commandContext));\r\n        } catch (IllegalStateException e) {\r\n            throw new ActivitiException(\"IllegalStateException while registering synchronization \", e);\r\n        } catch (RollbackException e) {\r\n            throw new ActivitiException(\"RollbackException while registering synchronization \", e);\r\n        } catch (SystemException e) {\r\n            throw new ActivitiException(\"SystemException while registering synchronization \", e);\r\n        }\r\n    }\r\n\r\n    public static class TransactionStateSynchronization implements Synchronization {\r\n\r\n        protected final TransactionListener transactionListener;\r\n        protected final TransactionState transactionState;\r\n        private final CommandContext commandContext;\r\n\r\n        public TransactionStateSynchronization(TransactionState transactionState, TransactionListener transactionListener, CommandContext commandContext) {\r\n            this.transactionState = transactionState;\r\n            this.transactionListener = transactionListener;\r\n            this.commandContext = commandContext;\r\n        }\r\n\r\n        @Override\r\n        public void beforeCompletion() {\r\n            if (TransactionState.COMMITTING == transactionState\r","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/jta/JtaTransactionContext.java#L63-L99","documentation":"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.","triggerScenarios":"Calling addTransactionListener when the JTA transaction manager or its resources are malfunctioning — transaction service error, resource adapter failure, or recoverable internal error.","commonSituations":"App-server transaction service instability; XA resource failures mid-transaction; engine running against a JTA implementation with known bugs (older JBossTS versions).","solutions":["Read the chained SystemException cause and the app-server transaction logs for the root failure.","Verify XA datasource and transaction recovery manager configuration.","Upgrade the app server / JTA provider — some SystemException cases are fixed provider bugs.","Retry the command once the transaction service is healthy; escalate to infrastructure if persistent."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-flight: ensure the JTA provider responds\ntransactionManager.getStatus();","typeGuard":null,"tryCatchPattern":"try { ctx.addTransactionListener(state, listener); } catch (ActivitiException e) { if (e.getCause() instanceof SystemException) { alertOps(\"JTA provider failure during synchronization registration\"); } else { throw e; } }","preventionTips":["Monitor transaction service and XA resource health.","Upgrade the app server / JTA provider to a stable version.","Keep recovery manager configuration correct."],"tags":["jta","transaction","synchronization","system-exception"],"backgroundTag":"database-write-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T16:30:33.424Z"}