quarkusio/quarkus · error · ConfigurationException

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

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.

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
Defensive patterns

Strategy: validation

Validate before calling

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");

Prevention

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

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

Appendix: 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)