apache/seatunnel · error · JdbcConnectorException

COMMON_WRITER_OPERATION_FAILED

COMMON_WRITER_OPERATION_FAILED

Error message

unable to open JDBC exactly one writer

What it means

JdbcExactlyOnceSinkWriter.tryOpen() wraps every exception raised while restoring XA state, rolling back stale transactions, and beginning the first XA transaction into a single WRITER_OPERATION_FAILED error. It means the exactly-once sink writer could not reach an operational state: the XA datasource was unusable or the initial transaction could not be started. The root cause is always attached as the cause.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/sink/JdbcExactlyOnceSinkWriter.java:139

        this.xidGenerator = xidGenerator;
        this.outputFormat = outputFormat;
    }

    private void tryOpen() {
        if (!isOpen) {
            isOpen = true;
            try {
                xidGenerator.open();
                xaFacade.open();
                outputFormat.open();
                if (!recoverStates.isEmpty()) {
                    Xid excludeXid = recoverStates.get(0).getXid();
                    // Rollback pending transactions that should not include recoverStates.
                    xaGroupOps.recoverAndRollback(context, sinkcontext, xidGenerator, excludeXid);
                }
                beginTx(System.currentTimeMillis());
            } catch (Exception e) {
                throw new JdbcConnectorException(
                        CommonErrorCodeDeprecated.WRITER_OPERATION_FAILED,
                        "unable to open JDBC exactly one writer",
                        e);
            }
        }
    }

    @Override
    public List<JdbcSinkState> snapshotState(long checkpointId) {
        checkState(prepareXid != null, "prepare xid must not be null");
        return Collections.singletonList(new JdbcSinkState(prepareXid));
    }

    @Override
    public void write(SeaTunnelRow element) {
        if (element.getArity() == 0) {
            return;
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Inspect the wrapped cause 'e' in the exception message/log for the real JDBC/XA error and fix that first
2. Verify the JDBC URL, username, and password in the sink connection config by connecting manually
3. Grant the DB user XA privileges required for two-phase commit (MySQL 8: GRANT XA_RECOVER_ADMIN; PostgreSQL: configured max_prepared_transactions > 0)
4. Check network/firewall/DNS connectivity from the SeaTunnel worker nodes to the database
5. Restart the job after fixing; if it persists, check recovered transaction state with the DB's XA recovery commands (XA RECOVER / pg_prepared_xacts)

Example fix

// before
url = "jdbc:mysql://db-host:3306/db"  // user lacks XA privileges
// after
url = "jdbc:mysql://db-host:3306/db?serverTimezone=UTC"
-- GRANT XA_RECOVER_ADMIN ON *.* TO 'seatunnel'@'%';

// before submitting the job
try (Connection c = DriverManager.getConnection(url, user, pass)) {
    if (!c.getMetaData().supportsXaTransactions()) throw new IllegalStateException("XA unsupported");
}

boolean canUseXaSink(DatabaseMetaData md) { try { return md.supportsXaTransactions(); } catch (SQLException e) { return false; } }

try { writer.open(); } catch (JdbcConnectorException e) { log.error("exactly-once writer open failed: {}", e.getCause(), e); throw e; }

When it happens

Trigger: JdbcSinkWriter.tryOpen() is called from write() and prepareCommit(); any Exception from xaGroupOps.recoverAndRollback(...) or beginTx(...) (e.g. xaFacade.open/start failure) in the stateful initialization block is caught and rethrown as this error.

Common situations: Wrong JDBC URL/credentials so the XA connection fails; database user lacking XA privileges (e.g. MySQL XA_RECOVER_ADMIN, Oracle XA recovery perms); MariaDB/PostgreSQL XA not enabled; network outage to the database at task startup; a broken XidGenerator or corrupted recovered checkpoint state causing recoverAndRollback to fail.

Related errors

• XA_OPERATION_FAILED
• COMMON_WRITER_OPERATION_FAILED
• XA_OPERATION_FAILED
• Exactly once is enabled, but not found primary key or unique
• CONNECT_FAILED

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/923c8ca7c07a4866. Report an issue: GitHub.