{"record":{"id":"cb202c0c9f42b8b3","repo":"apache/shardingsphere","slug":"25000","errorCode":"25000","errorMessage":"Failed to create '%s' XA data source.","messagePattern":"Failed to create '(.+?)' XA data source\\.","errorType":"exception","errorClass":"XADataSourceInitializeException","httpStatus":null,"severity":"critical","filePath":"kernel/transaction/type/xa/core/src/main/java/org/apache/shardingsphere/transaction/xa/jta/datasource/swapper/DataSourceSwapper.java","lineNumber":69,"sourceCode":"     * Swap data source to database access configuration.\n     *\n     * @param dataSource data source\n     * @return XADataSource XA data source\n     */\n    public XADataSource swap(final DataSource dataSource) {\n        XADataSource result = createXADataSource();\n        setProperties(result, getDatabaseAccessConfiguration(dataSource));\n        return result;\n    }\n    \n    private XADataSource createXADataSource() {\n        for (String each : xaDriverClassNames) {\n            try {\n                return loadXADataSource(each);\n            } catch (final ReflectiveOperationException ignored) {\n            }\n        }\n        throw new XADataSourceInitializeException(databaseType);\n    }\n    \n    private XADataSource loadXADataSource(final String xaDataSourceClassName) throws ReflectiveOperationException {\n        Class<?> xaDataSourceClass;\n        try {\n            xaDataSourceClass = Thread.currentThread().getContextClassLoader().loadClass(xaDataSourceClassName);\n        } catch (final ClassNotFoundException ignored) {\n            xaDataSourceClass = Class.forName(xaDataSourceClassName);\n        }\n        return (XADataSource) xaDataSourceClass.getDeclaredConstructor().newInstance();\n    }\n    \n    private Map<String, Object> getDatabaseAccessConfiguration(final DataSource dataSource) {\n        Map<String, Object> result = new HashMap<>(3, 1F);\n        Map<String, Object> standardProps = DataSourcePoolPropertiesCreator.create(\n                dataSource instanceof CatalogSwitchableDataSource ? ((CatalogSwitchableDataSource) dataSource).getDataSource() : dataSource).getAllStandardProperties();\n        result.put(\"url\", dataSource instanceof CatalogSwitchableDataSource ? ((CatalogSwitchableDataSource) dataSource).getUrl() : standardProps.get(\"url\"));\n        result.put(\"user\", standardProps.get(\"username\"));","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/kernel/transaction/type/xa/core/src/main/java/org/apache/shardingsphere/transaction/xa/jta/datasource/swapper/DataSourceSwapper.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the full JDBC driver jar (correct version for your database) to the proxy's lib directory or application classpath and restart.","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).","Upgrade to a driver version whose XA implementation matches the class names ShardingSphere probes for your database type.","If you cannot provide an XA-capable driver, use DEFAULT_TYPE=LOCAL or BASE instead of XA.","Enable reflection-friendly startup: check the server log for the swallowed ReflectiveOperationException causes before this exception."],"exampleFix":"# before: proxy/lib contains only mysql-connector-java-5.1.x with renamed XA class\n# after: replace with a matching full driver\ncp mysql-connector-j-8.0.33.jar /opt/shardingsphere-proxy/lib/\n# then restart the proxy so XA data source swapper can load com.mysql.cj.jdbc.MysqlXADataSource","handlingStrategy":"validation","validationCode":"// before enabling XA: verify the vendor XADataSource class loads\nClass<?> c = Class.forName(\"com.mysql.cj.jdbc.MysqlXADataSource\"); // throws ClassNotFoundException if driver missing\nXADataSource ds = (XADataSource) c.getDeclaredConstructor().newInstance();","typeGuard":null,"tryCatchPattern":"try { dataSource = swapper.swap(dataSource); } catch (final XADataSourceInitializeException ex) { /* driver jar missing/incompatible: add matching driver, or fall back to LOCAL/BASE */ }","preventionTips":["Ship the full JDBC driver jar matching your database and proxy version in lib/.","Smoke-test the vendor *XADataSource class on the classpath before switching DEFAULT_TYPE to XA.","Keep driver versions aligned with the database server.","If an XA-capable driver cannot be provided, use LOCAL or BASE transaction type."],"tags":["xa","transaction","driver","classpath","configuration"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}