What causes "The instance failed to implement this method" in apache/seatunnel?

Close and recreate the whole XaFacade (call close() then open()) instead of calling reestablishConnection.

apache/seatunnel · error · JdbcConnectorException

COMMON_UNSUPPORTED_OPERATION

COMMON_UNSUPPORTED_OPERATION

Error message

The instance failed to implement this method

What it means

XaFacadeImplAutoLoad does not support re-establishing a broken physical connection: reestablishConnection is intentionally unimplemented and always throws UNSUPPORTED_OPERATION. XA connections must be recovered through the XA protocol rather than silently reconnected.

Solutions

Close and recreate the whole XaFacade (call close() then open()) instead of calling reestablishConnection.
Rely on the engine's checkpoint restart: fail the task so it restarts with a fresh facade.
Update SeaTunnel if a newer version implements connection re-establishment for this facade.
Reduce transient disconnects (idle keepalive, network stability) to avoid reaching this code path.

Example fix

// before
xaFacade.reestablishConnection();
// after
xaFacade.close();
xaFacade.open();

Defensive patterns

Strategy: try-catch

Try / catch

try {
  xaFacade.reestablishConnection();
} catch (JdbcConnectorException e) {
  if (CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION.equals(e.getErrorCode())) {
    xaFacade.close();
    xaFacade.open(); // rebuild the facade instead
  }
}

Prevention

Never call reestablishConnection on the auto-load XA facade; recreate the facade instead.
Design job recovery around checkpoint restarts rather than in-place reconnection.
Keep connections alive (keepalive/idle settings) to reduce dropped XA connections.
Check newer SeaTunnel versions for implemented reconnection support.

When it happens

Trigger: Any code path (typically the recovery/reconnect logic in the XA group operations after a network failure) invokes reestablishConnection() on the auto-load XA facade instance.

Common situations: Long-running exactly-once sink jobs whose XA connection drops mid-transaction; failover of the database node during a checkpoint; calling the facade API directly in custom code.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/xa/XaFacadeImplAutoLoad.java:173

    public Connection getOrEstablishConnection() throws SQLException {
        if (!isOpen()) {
            open();
        }
        return connection;
    }

    @Override
    public void closeConnection() {
        try {
            close();
        } catch (SQLException e) {
            LOG.warn("Connection close failed.", e);
        }
    }

    @Override
    public Connection reestablishConnection() {
        throw new JdbcConnectorException(
                CommonErrorCodeDeprecated.UNSUPPORTED_OPERATION,
                "The instance failed to implement this method");
    }

    @Override
    public void start(Xid xid) {
        execute(Command.fromRunnable("start", xid, () -> xaResource.start(xid, TMNOFLAGS)));
    }

    @Override
    public void endAndPrepare(Xid xid) {
        execute(Command.fromRunnable("end", xid, () -> xaResource.end(xid, XAResource.TMSUCCESS)));
        int prepResult = execute(new Command<>("prepare", of(xid), () -> xaResource.prepare(xid)));
        if (prepResult == XAResource.XA_RDONLY) {
            throw new JdbcConnectorException(
                    JdbcConnectorErrorCode.XA_OPERATION_FAILED,
                    new EmptyXaTransactionException(xid));
        } else if (prepResult != XAResource.XA_OK) {

View on GitHub (pinned to cf67b549a7)