quarkusio/quarkus · error · ConfigurationException

Driver is not an XA dataSource, while XA has been enabled in

Error message

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

What it means

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.

Source

Thrown at extensions/agroal/deployment/src/main/java/io/quarkus/agroal/deployment/component/DataSourceDefinitionBlockingProcessor.java:218

    }

    private static void validateBuildTimeConfig(JdbcDataSourceDefinitionBuildItem aggregatedConfig) {
        DataSourceJdbcBuildTimeConfig jdbcBuildTimeConfig = aggregatedConfig.getJdbcConfig();

        String fullDataSourceName = aggregatedConfig.isDefault() ? "default datasource"
                : "datasource named '" + aggregatedConfig.getName() + "'";

        String driverName = aggregatedConfig.getResolvedDriverClass();
        Class<?> driver;
        try {
            driver = Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());
        } catch (ClassNotFoundException e) {
            throw new ConfigurationException(
                    "Unable to load the datasource driver " + driverName + " for the " + fullDataSourceName, e);
        }
        if (jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA) {
            if (!XADataSource.class.isAssignableFrom(driver)) {
                throw new ConfigurationException(
                        "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");
            }
        } else {
            if (driver != null && !javax.sql.DataSource.class.isAssignableFrom(driver)
                    && !Driver.class.isAssignableFrom(driver)) {
                if (aggregatedConfig.isDefault()) {
                    throw new ConfigurationException(
                            "Driver " + driverName
                                    + " 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");
                } else {
                    throw new ConfigurationException(
                            "Driver " + driverName
                                    + " is an XA datasource, but XA transactions have not been enabled on the datasource named '"
                                    + fullDataSourceName + "'; please either set 'quarkus.datasource." + fullDataSourceName
                                    + ".jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation");
                }
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Switch the driver to an XADataSource implementation (e.g. org.postgresql.xa.PGXADataSource).
2. Or disable XA: set quarkus.datasource.jdbc.transactions=enabled (or remove the xa setting).

Example fix

// before
quarkus.datasource.jdbc.transactions=xa
quarkus.datasource.jdbc.driver=org.postgresql.Driver // not XA
// after
quarkus.datasource.jdbc.transactions=xa
quarkus.datasource.jdbc.driver=org.postgresql.xa.PGXADataSource

boolean xa = "xa".equals(ConfigProvider.getConfig().getValue("quarkus.datasource.jdbc.transactions", String.class));
Class<?> d = Class.forName(ConfigProvider.getConfig().getValue("quarkus.datasource.jdbc.driver", String.class));
if (xa && !javax.sql.XADataSource.class.isAssignableFrom(d)) throw new IllegalStateException("XA enabled but driver is not XADataSource");

When it happens

Trigger: validateBuildTimeConfig() (via defineJdbcDataSources) checks jdbcBuildTimeConfig.transactions() == TransactionIntegration.XA and fails !XADataSource.class.isAssignableFrom(driver) for the resolved driver class of fullDataSourceName.

Common situations: 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.

Related errors

• Driver <driverName> is an XA datasource, but XA transactions
• Driver <driverName> is an XA datasource, but XA transactions
• Unable to load the datasource driver <driverName> for the <f
• Unable to find a JDBC driver corresponding to the database k
• The Agroal extension is missing and it is required when a Qu

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/4e10e46cfb5a0a66. Report an issue: GitHub.