quarkusio/quarkus · error · ConfigurationException

Driver <driverName> is an XA datasource, but XA transactions

Error message

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

What it means

The inverse of the XA mismatch: validateBuildTimeConfig() detects that the configured driver IS an XADataSource while XA transactions were not enabled. For the default datasource it throws this ConfigurationException telling the user to either enable XA or use a non-XA driver.

Source

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

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

    private String resolveDriver(String dataSourceName, String dbKind,
            DataSourceJdbcBuildTimeConfig dataSourceJdbcBuildTimeConfig, List<JdbcDriverBuildItem> jdbcDriverBuildItems) {
        if (dataSourceJdbcBuildTimeConfig.driver().isPresent()) {
            return dataSourceJdbcBuildTimeConfig.driver().get();
        }

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.datasource.jdbc.transactions=xa on the default datasource.
Or switch to a standard non-XA driver (e.g. org.postgresql.Driver).

Example fix

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

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 driver requires transactions=xa");

Prevention

Pair every XA driver class with quarkus.datasource.jdbc.transactions=xa.
Otherwise use the plain non-XA driver class.

When it happens

Trigger: jdbcBuildTimeConfig.transactions() != XA, the loaded driver is neither javax.sql.DataSource nor java.sql.Driver assignable (i.e. it is an XADataSource), and aggregatedConfig.isDefault() is true.

Common situations: Configuring an XA driver class (e.g. org.postgresql.xa.PGXADataSource) but forgetting quarkus.datasource.jdbc.transactions=xa on the default datasource.

Related errors

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