{"record":{"id":"d8a225d33250348a","repo":"apache/seatunnel","slug":"xa-operation-failed-d8a225","errorCode":"XA_OPERATION_FAILED","errorMessage":"unable to start xa transaction, xid=%s","messagePattern":"unable to start xa transaction, xid=(.+?)","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcExactlyOnceSinkWriter.java","lineNumber":233,"sourceCode":"                    e);\n        } finally {\n            outputFormat.close();\n            xidGenerator.close();\n            currentXid = null;\n            prepareXid = null;\n        }\n    }\n\n    private void beginTx(long txIdHint) throws IOException {\n        checkState(currentXid == null, \"currentXid not null\");\n        long txId = nextTxId(txIdHint);\n        currentXid = xidGenerator.generateXid(context, sinkcontext, txId);\n        try {\n            xaFacade.start(currentXid);\n        } catch (Exception e) {\n            Xid xid = currentXid;\n            currentXid = null;\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.XA_OPERATION_FAILED,\n                    String.format(\"unable to start xa transaction, xid=%s\", xid),\n                    e);\n        }\n    }\n\n    private long nextTxId(long txIdHint) {\n        long candidate = txIdHint;\n        if (candidate <= lastGeneratedTxId) {\n            checkState(lastGeneratedTxId != Long.MAX_VALUE, \"tx id exhausted\");\n            candidate = lastGeneratedTxId + 1;\n        }\n        lastGeneratedTxId = candidate;\n        return candidate;\n    }\n\n    private void rollbackPrepareXidQuietly() {\n        if (prepareXid == null || !xaFacade.isOpen()) {","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcExactlyOnceSinkWriter.java#L215-L251","documentation":"beginTx() generates an Xid and calls xaFacade.start(currentXid) to begin an XA transaction; if start fails, the error carries the specific xid and code XA_OPERATION_FAILED. This happens on every new transaction started by the exactly-once writer (initial open and each prepareCommit), so it typically means the database refused the XA START.","triggerScenarios":"beginTx is invoked by tryOpen (first transaction) and prepareCommit (each checkpoint interval); xaFacade.start fails when the underlying connection cannot start the XA transaction (connection dead, DB rejecting XA, duplicate xid).","commonSituations":"Connection killed by idle timeout between checkpoints; MySQL 'XAER_DUPID' from xid collision (weak xidGenerator across restarted jobs); database XA unsupported or misconfigured; DB outage at checkpoint time.","solutions":["Read the xid in the message and the cause: XAER_RMFAIL => reconnectivity issue; XAER_DUPID => xid collision","Fix network/keepalive settings so the connection survives between checkpoints (e.g. TCP keepalive, connection pool validation)","Ensure the XidGenerator produces unique xids per job/restart (check job id/seed configuration)","Confirm the DB supports XA and max_prepared_transactions (PostgreSQL) is > 0"],"exampleFix":"// before\nxaFacade.start(currentXid) // fails: connection idle-dead after long checkpoint interval\n// after\njdbc_url += \"?tcpKeepAlive=true&autoReconnect=false\" // and reduce checkpoint interval","handlingStrategy":"retry","validationCode":"// verify XA start capability\ntry (XAConnection xa = xaDs.getXAConnection(); XAResource r = xa.getXAResource()) {\n    Xid test = new XidImpl(); r.start(test, XAResource.TMNOFLAGS); r.end(test, XAResource.TMSUCCESS); r.forget(test);\n}","typeGuard":null,"tryCatchPattern":"catch (JdbcConnectorException e) { if (String.valueOf(e.getCause()).contains(\"XAER_DUPID\")) fixXidGenerator(); else retryWithBackoff(); }","preventionTips":["Use unique xids per job run (configure distinct job id / xid prefix)","Keep checkpoint intervals shorter than connection idle timeouts","Enable TCP keepalive on the JDBC URL","Confirm the DB supports XA and two-phase commit"],"tags":["jdbc","xa","transaction","exactly-once"],"backgroundTag":"xa-transaction-start-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}