What causes "No pool has been defined for persistence unit " in quarkusio/quarkus?

Define the datasource: quarkus.datasource.db-kind (and quarkus.datasource.username/password, reactive url) in application.properties

quarkusio/quarkus · critical · IllegalStateException

No pool has been defined for persistence unit

Error message

No pool has been defined for persistence unit

What it means

A Hibernate Reactive persistence unit must be backed by an Agroal datasource (reactive Pool). When the Pool CDI instance for the PU's datasource is not resolvable, Quarkus throws IllegalStateException 'No pool has been defined for persistence unit ...' (wrapped by unableToFindDataSource on other RuntimeExceptions).

Source

Thrown at extensions/hibernate-reactive/runtime/src/main/java/io/quarkus/hibernate/reactive/runtime/FastBootHibernateReactivePersistenceProvider.java:384

        return FastBootHibernateReactivePersistenceProvider.class.getName().equals(requestedProviderName)
                || IMPLEMENTATION_NAME.equals(requestedProviderName)
                || FastBootHibernatePersistenceProvider.class.getName().equals(requestedProviderName)
                || "org.hibernate.jpa.HibernatePersistenceProvider".equals(requestedProviderName);
    }

    private void registerVertxAndPool(String persistenceUnitName,
            RuntimeSettings runtimeSettings,
            PreconfiguredReactiveServiceRegistryBuilder serviceRegistry, String datasourceName) {
        if (runtimeSettings.isConfigured(AvailableSettings.URL)) {
            // the pool has been defined in the persistence unit, we can bail out
            return;
        }

        Pool pool;
        try {
            InjectableInstance<Pool> poolHandle = ReactiveDataSourceUtil.dataSourceInstance(datasourceName);
            if (!poolHandle.isResolvable()) {
                throw new IllegalStateException("No pool has been defined for persistence unit " + persistenceUnitName);
            }
            // ClientProxy.unwrap is necessary to trigger exceptions on inactive datasources
            pool = ClientProxy.unwrap(poolHandle.get());
        } catch (RuntimeException e) {
            throw PersistenceUnitUtil.unableToFindDataSource(persistenceUnitName, datasourceName, e);
        }

        serviceRegistry.addInitiator(new QuarkusReactiveConnectionPoolInitiator(pool));

        InstanceHandle<Vertx> vertxHandle = Arc.container().instance(Vertx.class);
        if (!vertxHandle.isAvailable()) {
            throw new IllegalStateException("No Vert.x instance has been registered in ArC ?");
        }
        serviceRegistry.addInitiator(new VertxInstanceInitiator(vertxHandle.get()));
    }

    private static void injectRuntimeConfiguration(HibernateOrmRuntimeConfigPersistenceUnit persistenceUnitConfig,
            Builder runtimeSettingsBuilder) {

View on GitHub (pinned to e1c734241f)

Solutions

Define the datasource: quarkus.datasource.db-kind (and quarkus.datasource.username/password, reactive url) in application.properties
If the PU uses a named datasource, configure quarkus.datasource."<name>".* with the exact name referenced by quarkus.hibernate-orm.datasource
Ensure quarkus-agroal (and reactive client driver, e.g., io.quarkus:quarkus-reactive-pg-client) dependencies are present
Fix typos/mismatch between the PU datasource name and the configured datasource

Example fix

// before (application.properties)
quarkus.hibernate-orm.datasource=customers
# no datasource named 'customers' configured

// after
quarkus.hibernate-orm.datasource=customers
quarkus.datasource."customers".db-kind=postgresql
quarkus.datasource."customers".reactive.url=vertx-postgresql://localhost:5432/customers

Defensive patterns

Strategy: validation

Validate before calling

String dsName = config.datasource().orElse("<default>");
boolean poolExists = Arc.container().instance(DataSource.class, DataSourceUtil.dataSourceNameQualifier(dsName)).isResolvable();
if (!poolExists) throw new IllegalStateException("Configure quarkus.datasource for " + dsName);

Type guard

boolean datasourceConfigured(String name) {
    return Arc.container() != null
        && Arc.container().instance(DataSource.class,
             DataSourceUtil.dataSourceNameQualifier(name)).isResolvable();
}

Try / catch

try {
    sessionFactory = quarkusFactory();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("No pool has been defined")) { failFast("Configure the datasource"); }
    throw e;
}

Prevention

Match quarkus.hibernate-orm.datasource exactly to a quarkus.datasource."name" config key
Always add quarkus-agroal and the reactive client driver when using hibernate-reactive
Smoke-test datasource resolution at startup in every environment

When it happens

Trigger: Bootstrapping a reactive persistence unit whose configured datasource (quarkus.hibernate-orm.datasource or the default datasource) has no matching quarkus.datasource."name".db-kind / reactive pool configuration; detected in registerVertxAndPool via ReactiveDataSourceUtil.dataSourceInstance(datasourceName).

Common situations: PU points at a named datasource that isn't configured (typo in quarkus.hibernate-orm.datasource vs quarkus.datasource key); no datasource at all defined; hibernate-reactive used without an Agroal/reactive datasource extension; datasource deactivated at runtime.

Related errors

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