{"record":{"id":"bd33c570564c9b5a","repo":"apache/seatunnel","slug":"connect-database-failed-bd33c5","errorCode":"CONNECT_DATABASE_FAILED","errorMessage":"unable to build XADataSource","messagePattern":"unable to build XADataSource","errorType":"error_code","errorClass":"JdbcConnectorException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/xa/XaFacadeImplAutoLoad.java","lineNumber":97,"sourceCode":"    private static final int MAX_RECOVER_CALLS = 100;\n\n    private final JdbcConnectionConfig jdbcConnectionConfig;\n    private transient XAResource xaResource;\n    private transient Connection connection;\n    private transient XAConnection xaConnection;\n\n    XaFacadeImplAutoLoad(JdbcConnectionConfig jdbcConnectionConfig) {\n        this.jdbcConnectionConfig = jdbcConnectionConfig;\n    }\n\n    @Override\n    public void open() throws SQLException {\n        checkState(!isOpen(), \"already connected\");\n        XADataSource ds;\n        try {\n            ds = (XADataSource) DataSourceUtils.buildCommonDataSource(jdbcConnectionConfig);\n        } catch (Exception e) {\n            throw new JdbcConnectorException(\n                    JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED,\n                    \"unable to build XADataSource\",\n                    e);\n        }\n        xaConnection = ds.getXAConnection();\n        xaResource = xaConnection.getXAResource();\n        if (jdbcConnectionConfig.getTransactionTimeoutSec().isPresent()) {\n            try {\n                xaResource.setTransactionTimeout(\n                        jdbcConnectionConfig.getTransactionTimeoutSec().get());\n            } catch (XAException e) {\n                throw new JdbcConnectorException(\n                        JdbcConnectorErrorCode.XA_OPERATION_FAILED,\n                        \"unable to set XA transaction timeout\",\n                        e);\n            }\n        }\n        connection = xaConnection.getConnection();","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/xa/XaFacadeImplAutoLoad.java#L79-L115","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause 'e' for the root reason (ClassNotFound vs bad URL vs auth).","Ensure the JDBC driver jar is in $SEATUNNEL_HOME/plugins/jdbc/lib (or the connector's lib directory).","Verify url and driver_class_name in the sink config match your database (e.g. jdbc:postgresql://host:5432/db and org.postgresql.Driver).","Confirm the database/driver supports XA (XADataSource); otherwise use a non-XA exactly-once option."],"exampleFix":"// before\nurl = \"jdbc:postgres://host:5432/db\"\n// after\nurl = \"jdbc:postgresql://host:5432/db\"\ndriver = \"org.postgresql.Driver\"","handlingStrategy":"validation","validationCode":"// preflight the config before enabling XA\nassert url.startsWith(\"jdbc:\");\nassert driverClassName != null && !driverClassName.isEmpty();\nClass.forName(driverClassName); // driver must be on classpath","typeGuard":null,"tryCatchPattern":"try {\n  xaFacade.open();\n} catch (JdbcConnectorException e) {\n  if (JdbcConnectorErrorCode.CONNECT_DATABASE_FAILED.equals(e.getErrorCode())) {\n    log.error(\"XA datasource build failed: {}\", e.getCause(), e.getCause());\n  }\n  throw e;\n}","preventionTips":["Install the JDBC driver jar in the connector's plugin/lib directory.","Double-check url, driver, user, and password in the sink config.","Confirm the target database and driver expose a working XADataSource.","Validate the URL format against the specific database's documented JDBC URL."],"tags":["jdbc","xa","datasource","config"],"backgroundTag":"invalid-config-value","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"}