apache/shardingsphere · critical · XADataSourceInitializeException

25000

25000

Error message

Failed to create '%s' XA data source.

What it means

When XA transactions are enabled, DataSourceSwapper converts the regular DataSource into an XADataSource. It iterates the candidate xaDriverClassNames for the database type, attempting to load and instantiate each via reflection; if every attempt fails with ReflectiveOperationException (class missing or not an XADataSource), it throws XADataSourceInitializeException (SQLSTATE class 25000) with the message 'Failed to create '%s' XA data source.' naming the database type.

Source

Thrown at kernel/transaction/type/xa/core/src/main/java/org/apache/shardingsphere/transaction/xa/jta/datasource/swapper/DataSourceSwapper.java:69

     * Swap data source to database access configuration.
     *
     * @param dataSource data source
     * @return XADataSource XA data source
     */
    public XADataSource swap(final DataSource dataSource) {
        XADataSource result = createXADataSource();
        setProperties(result, getDatabaseAccessConfiguration(dataSource));
        return result;
    }
    
    private XADataSource createXADataSource() {
        for (String each : xaDriverClassNames) {
            try {
                return loadXADataSource(each);
            } catch (final ReflectiveOperationException ignored) {
            }
        }
        throw new XADataSourceInitializeException(databaseType);
    }
    
    private XADataSource loadXADataSource(final String xaDataSourceClassName) throws ReflectiveOperationException {
        Class<?> xaDataSourceClass;
        try {
            xaDataSourceClass = Thread.currentThread().getContextClassLoader().loadClass(xaDataSourceClassName);
        } catch (final ClassNotFoundException ignored) {
            xaDataSourceClass = Class.forName(xaDataSourceClassName);
        }
        return (XADataSource) xaDataSourceClass.getDeclaredConstructor().newInstance();
    }
    
    private Map<String, Object> getDatabaseAccessConfiguration(final DataSource dataSource) {
        Map<String, Object> result = new HashMap<>(3, 1F);
        Map<String, Object> standardProps = DataSourcePoolPropertiesCreator.create(
                dataSource instanceof CatalogSwitchableDataSource ? ((CatalogSwitchableDataSource) dataSource).getDataSource() : dataSource).getAllStandardProperties();
        result.put("url", dataSource instanceof CatalogSwitchableDataSource ? ((CatalogSwitchableDataSource) dataSource).getUrl() : standardProps.get("url"));
        result.put("user", standardProps.get("username"));

View on GitHub (pinned to e952770a21)

Solutions

1. Add the full JDBC driver jar (correct version for your database) to the proxy's lib directory or application classpath and restart.
2. Verify the expected XADataSource class exists: scan the jar for the vendor's *XADataSource class (e.g. com.mysql.cj.jdbc.MysqlXADataSource, org.postgresql.xa.PGXADataSource).
3. Upgrade to a driver version whose XA implementation matches the class names ShardingSphere probes for your database type.
4. If you cannot provide an XA-capable driver, use DEFAULT_TYPE=LOCAL or BASE instead of XA.
5. Enable reflection-friendly startup: check the server log for the swallowed ReflectiveOperationException causes before this exception.

Example fix

# before: proxy/lib contains only mysql-connector-java-5.1.x with renamed XA class
# after: replace with a matching full driver
cp mysql-connector-j-8.0.33.jar /opt/shardingsphere-proxy/lib/
# then restart the proxy so XA data source swapper can load com.mysql.cj.jdbc.MysqlXADataSource

// before enabling XA: verify the vendor XADataSource class loads
Class<?> c = Class.forName("com.mysql.cj.jdbc.MysqlXADataSource"); // throws ClassNotFoundException if driver missing
XADataSource ds = (XADataSource) c.getDeclaredConstructor().newInstance();

try { dataSource = swapper.swap(dataSource); } catch (final XADataSourceInitializeException ex) { /* driver jar missing/incompatible: add matching driver, or fall back to LOCAL/BASE */ }

When it happens

Trigger: Setting transaction rule DEFAULT_TYPE=XA for a datasource whose JDBC driver jar either is absent from the classpath or does not expose the expected XADataSource implementation class (e.g. MySQL Connector/J missing or a driver stub without com.mysql.cj.jdbc.MysqlXADataSource). The ReflectiveOperationException is swallowed per candidate, so the failure surfaces only as this exception.

Common situations: Missing or too-old MySQL/PostgreSQL/Oracle driver jar in proxy/lib or JDBC classpath; using a repackaged/shaded driver where the XA class name differs; driver present but its XA class fails to instantiate (missing native libs); adding a new database type without verifying its XA mapping.

Related errors

• 0
• Can not locate agent jar file by URL `%s`.
• Can not find field name `%s` in class %s.
• Could not load class: %s
• 41

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/cb202c0c9f42b8b3. Report an issue: GitHub.