apache/seatunnel · critical · JdbcConnectorException

CONNECT_DATABASE_FAILED

CONNECT_DATABASE_FAILED

Error message

unable to build XADataSource

What it means

XaFacadeImplAutoLoad.open builds an XADataSource from the user's JDBC connection config via DataSourceUtils.buildCommonDataSource. If that construction throws for any reason (bad URL, missing driver class, unsupported dialect, invalid credentials), the exception is wrapped as CONNECT_DATABASE_FAILED with the message 'unable to build XADataSource'.

Source

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

    private static final int MAX_RECOVER_CALLS = 100;

    private final JdbcConnectionConfig jdbcConnectionConfig;
    private transient XAResource xaResource;
    private transient Connection connection;
    private transient XAConnection xaConnection;

    XaFacadeImplAutoLoad(JdbcConnectionConfig jdbcConnectionConfig) {
        this.jdbcConnectionConfig = jdbcConnectionConfig;
    }

    @Override
    public void open() throws SQLException {
        checkState(!isOpen(), "already connected");
        XADataSource ds;
        try {
            ds = (XADataSource) DataSourceUtils.buildCommonDataSource(jdbcConnectionConfig);
        } catch (Exception e) {
            throw new JdbcConnectorException(
                    JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,
                    "unable to build XADataSource",
                    e);
        }
        xaConnection = ds.getXAConnection();
        xaResource = xaConnection.getXAResource();
        if (jdbcConnectionConfig.getTransactionTimeoutSec().isPresent()) {
            try {
                xaResource.setTransactionTimeout(
                        jdbcConnectionConfig.getTransactionTimeoutSec().get());
            } catch (XAException e) {
                throw new JdbcConnectorException(
                        JdbcConnectorErrorCode.XA_OPERATION_FAILED,
                        "unable to set XA transaction timeout",
                        e);
            }
        }
        connection = xaConnection.getConnection();

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped cause 'e' for the root reason (ClassNotFound vs bad URL vs auth).
2. Ensure the JDBC driver jar is in $SEATUNNEL_HOME/plugins/jdbc/lib (or the connector's lib directory).
3. Verify url and driver_class_name in the sink config match your database (e.g. jdbc:postgresql://host:5432/db and org.postgresql.Driver).
4. Confirm the database/driver supports XA (XADataSource); otherwise use a non-XA exactly-once option.

Example fix

// before
url = "jdbc:postgres://host:5432/db"
// after
url = "jdbc:postgresql://host:5432/db"
driver = "org.postgresql.Driver"

// preflight the config before enabling XA
assert url.startsWith("jdbc:");
assert driverClassName != null && !driverClassName.isEmpty();
Class.forName(driverClassName); // driver must be on classpath

try {
  xaFacade.open();
} catch (JdbcConnectorException e) {
  if (JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED.equals(e.getErrorCode())) {
    log.error("XA datasource build failed: {}", e.getCause(), e.getCause());
  }
  throw e;
}

When it happens

Trigger: Calling getOrEstablishConnection/open on the XA facade in exactly-once (2PC/XA) sink mode when the jdbc URL, driver class name, or dialect in JdbcConnectionConfig is wrong or the driver is not on the classpath.

Common situations: Missing JDBC driver jar in the plugin directory; typo in driver_class_name; database doesn't provide an XADataSource for the configured dialect; wrong URL format for the database.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unsupported parameter type:
• oracle_insert_mode=APPEND_VALUES only supports generated INS
• oracle_insert_mode=APPEND_VALUES only supports Oracle JDBC s
• oracle_insert_mode=APPEND_VALUES only supports insert-only w
• CLASS_NOT_FOUND

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