What causes "Driver is an XA datasource, but XA transactions have not been enabled on the datasource named ' '; please either set 'quarkus.datasource. .jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation" in quarkusio/quarkus?

Set quarkus.datasource. .jdbc.transactions=xa for the named datasource.

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 datasource named '<fullDataSourceName>'; please either set 'quarkus.datasource.<fullDataSourceName>.jdbc.transactions=xa' or switch to a standard non-XA JDBC driver implementation

What it means

Same condition as error 526 (an XADataSource driver configured without transactions=xa) but for a named (non-default) datasource, so the message names the datasource and its property key quarkus.datasource.<name>.jdbc.transactions=xa.

Source

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

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

        Optional<JdbcDriverBuildItem> matchingJdbcDriver = jdbcDriverBuildItems.stream()
                .filter(i -> dbKind.equals(i.getDbKind()))
                .findFirst();

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.datasource.<name>.jdbc.transactions=xa for the named datasource.
Or switch that datasource's driver to a non-XA implementation (DataSource or Driver).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

String ds = "orders";
boolean xa = "xa".equals(ConfigProvider.getConfig().getValue("quarkus.datasource." + ds + ".jdbc.transactions", String.class));
Class<?> d = Class.forName(ConfigProvider.getConfig().getValue("quarkus.datasource." + ds + ".jdbc.driver", String.class));
if (!xa && javax.sql.XADataSource.class.isAssignableFrom(d)) throw new IllegalStateException("Datasource " + ds + " uses XA driver without transactions=xa");

Prevention

For each named datasource, verify driver class and transactions setting are consistent.
Do not copy default-datasource XA assumptions onto named datasources without setting their own transactions property.

When it happens

Trigger: jdbcBuildTimeConfig.transactions() != XA, the driver fails both DataSource and Driver assignability checks (it is an XADataSource), and aggregatedConfig.isDefault() is false; the message embeds fullDataSourceName.

Common situations: Named datasources (quarkus.datasource.orders.*) configured with an XA driver class but no transactions=xa for that named datasource.

Related errors

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