quarkusio/quarkus · error · HibernateException

A Datasource was configured as Connection Pool, but it's not

Error message

A Datasource was configured as Connection Pool, but it's not the Agroal connection pool. In Quarkus, you need to use Agroal.

What it means

QuarkusConnectionProviderInitiator installs Hibernate's connection provider. When Hibernate is configured with a datasource (AvailableSettings.DATASOURCE), Quarkus requires that object to be an AgroalDataSource; a cast to AgroalDataSource failing triggers this HibernateException, since Quarkus routes all JDBC pooling through Agroal.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/QuarkusConnectionProviderInitiator.java:41

    }

    @Override
    public ConnectionProvider initiateService(Map configurationValues, ServiceRegistryImplementor registry) {
        //First, check that this setup won't need to deal with multi-tenancy at the connection pool level:
        final MultiTenancyStrategy strategy = MultiTenancyStrategy.determineMultiTenancyStrategy(configurationValues);
        if (strategy == MultiTenancyStrategy.DATABASE || strategy == MultiTenancyStrategy.SCHEMA) {
            // nothing to do, but given the separate hierarchies have to handle this here.
            return null;
        }

        //Next, we'll want to try the Quarkus optimised pool:
        Object o = configurationValues.get(AvailableSettings.DATASOURCE);
        if (o != null) {
            final AgroalDataSource ds;
            try {
                ds = (AgroalDataSource) o;
            } catch (ClassCastException cce) {
                throw new HibernateException(
                        "A Datasource was configured as Connection Pool, but it's not the Agroal connection pool. In Quarkus, you need to use Agroal.");
            }
            return new QuarkusConnectionProvider(ds);
        }

        //When not using the Quarkus specific Datasource, delegate to traditional bootstrap so to not break
        //applications using persistence.xml :
        return ConnectionProviderInitiator.INSTANCE.initiateService(configurationValues, registry);
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Remove custom datasource wiring and use Quarkus' Agroal datasource config (quarkus.datasource.*), referenced via quarkus.hibernate-orm.datasource.
If you need a custom pool, configure Agroal instead (quarkus.datasource.jdbc.*) — do not inject Hikari or another pool.
If you wrap AgroalDataSource, unwrap to the underlying AgroalDataSource before assigning it as Hibernate's DATASOURCE property.

Example fix

// before
HikariDataSource ds = new HikariDataSource(cfg);
properties.put(AvailableSettings.DATASOURCE, ds);

// after (application.properties)
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=...
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/db

Defensive patterns

Strategy: type-guard

Validate before calling

Object o = properties.get(AvailableSettings.DATASOURCE);
if (o != null && !(o instanceof AgroalDataSource)) {
    throw new IllegalStateException("Hibernate DATASOURCE must be an AgroalDataSource, got: "
        + o.getClass().getName());
}

Type guard

boolean isAgroal(Object ds) {
    return ds instanceof AgroalDataSource;
}

Try / catch

try {
    sf = factory.buildSessionFactory();
} catch (HibernateException e) {
    if (e.getMessage().contains("not the Agroal connection pool")) {
        log.error("Configure Hibernate to use the Quarkus Agroal datasource (quarkus.datasource.*), not a custom pool");
    }
    throw e;
}

Prevention

Always use quarkus.datasource.* config and let Quarkus wire Agroal to Hibernate
Never assign Hikari/other pool DataSources to Hibernate's DATASOURCE property
If wrapping AgroalDataSource, unwrap before handing it to Hibernate
Do not mix persistence.xml datasource references with Quarkus datasources

When it happens

Trigger: Setting hibernate.connection.datasource (or the equivalent quarkus property / persistence.xml datasource JNDI setting) to a DataSource that is not Agroal's implementation — e.g. a HikariDataSource, a custom DataSource, or a wrapped/proxied DataSource — while bootstrapping the persistence unit.

Common situations: Porting Spring Boot/Hikari configurations into Quarkus; registering a custom DataSource bean and handing it to Hibernate; wrapping AgroalDataSource in a delegating tracing/metrics proxy that breaks the cast; mixing persistence.xml datasource references with Quarkus-managed datasources.

Related errors

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