{"record":{"id":"4e10e46cfb5a0a66","repo":"quarkusio/quarkus","slug":"driver-is-not-an-xa-datasource-while-xa-has-been","errorCode":null,"errorMessage":"Driver is not an XA dataSource, while XA has been enabled in the configuration of the <fullDataSourceName>: either disable XA or switch the driver to an XADataSource","messagePattern":"Driver is not an XA dataSource, while XA has been enabled in the configuration of the <fullDataSourceName>: either disable XA or switch the driver to an XADataSource","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java","lineNumber":218,"sourceCode":"    }\n\n    private static void validateBuildTimeConfig(JdbcDataSourceDefinitionBuildItem aggregatedConfig) {\n        DataSourceJdbcBuildTimeConfig jdbcBuildTimeConfig = aggregatedConfig.getJdbcConfig();\n\n        String fullDataSourceName = aggregatedConfig.isDefault() ? \"default datasource\"\n                : \"datasource named '\" + aggregatedConfig.getName() + \"'\";\n\n        String driverName = aggregatedConfig.getResolvedDriverClass();\n        Class<?> driver;\n        try {\n            driver = Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());\n        } catch (ClassNotFoundException e) {\n            throw new ConfigurationException(\n                    \"Unable to load the datasource driver \" + driverName + \" for the \" + fullDataSourceName, e);\n        }\n        if (jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA) {\n            if (!XADataSource.class.isAssignableFrom(driver)) {\n                throw new ConfigurationException(\n                        \"Driver is not an XA dataSource, while XA has been enabled in the configuration of the \"\n                                + fullDataSourceName + \": either disable XA or switch the driver to an XADataSource\");\n            }\n        } else {\n            if (driver != null && !javax.sql.DataSource.class.isAssignableFrom(driver)\n                    && !Driver.class.isAssignableFrom(driver)) {\n                if (aggregatedConfig.isDefault()) {\n                    throw new ConfigurationException(\n                            \"Driver \" + driverName\n                                    + \" is an XA datasource, but XA transactions have not been enabled on the default datasource; please either set 'quarkus.datasource.jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation\");\n                } else {\n                    throw new ConfigurationException(\n                            \"Driver \" + driverName\n                                    + \" is an XA datasource, but XA transactions have not been enabled on the datasource named '\"\n                                    + fullDataSourceName + \"'; please either set 'quarkus.datasource.\" + fullDataSourceName\n                                    + \".jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation\");\n                }\n            }","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java#L200-L236","documentation":"Agroal validates at build time that a datasource with transactions=xa uses a driver implementing javax.sql.XADataSource. validateBuildTimeConfig() throws this ConfigurationException when XA is enabled but the loaded driver is neither an XADataSource nor usable for XA transactions.","triggerScenarios":"validateBuildTimeConfig() (via defineJdbcDataSources) checks jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA and fails !XADataSource.class.isAssignableFrom(driver) for the resolved driver class of fullDataSourceName.","commonSituations":"Setting quarkus.datasource.jdbc.transactions=xa while using a plain Driver implementation (e.g. basic PostgreSQL driver setup); copying XA config onto a datasource whose driver only supports DataSource.","solutions":["Switch the driver to an XADataSource implementation (e.g. org.postgresql.xa.PGXADataSource).","Or disable XA: set quarkus.datasource.jdbc.transactions=enabled (or remove the xa setting)."],"exampleFix":"// before\nquarkus.datasource.jdbc.transactions=xa\nquarkus.datasource.jdbc.driver=org.postgresql.Driver // not XA\n// after\nquarkus.datasource.jdbc.transactions=xa\nquarkus.datasource.jdbc.driver=org.postgresql.xa.PGXADataSource","handlingStrategy":"validation","validationCode":"boolean xa = \"xa\".equals(ConfigProvider.getConfig().getValue(\"quarkus.datasource.jdbc.transactions\", String.class));\nClass<?> d = Class.forName(ConfigProvider.getConfig().getValue(\"quarkus.datasource.jdbc.driver\", String.class));\nif (xa && !javax.sql.XADataSource.class.isAssignableFrom(d)) throw new IllegalStateException(\"XA enabled but driver is not XADataSource\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set transactions=xa when the driver class implements javax.sql.XADataSource.","Keep non-XA default setups (transactions=enabled) unless XA is explicitly required."],"tags":["quarkus","agroal","jdbc","xa","transactions","build-time"],"backgroundTag":"xa-driver-mismatch","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}