quarkusio/quarkus · error · IllegalStateException

No instance of datasource found for persistence unit '%1$s'

Error message

No instance of datasource found for persistence unit '%1$s' and tenant '%2$s'

What it means

The multitenant Hibernate connection resolver could not find an Agroal datasource matching the given persistence unit and tenant id, so it cannot build a ConnectionProvider. It throws IllegalStateException naming both the PU and tenant.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/tenant/DataSourceTenantConnectionResolver.java:52

    public DataSourceTenantConnectionResolver() {
    }

    public DataSourceTenantConnectionResolver(String persistenceUnitName, Optional<String> dataSourceName,
            MultiTenancyStrategy multiTenancyStrategy) {
        this.persistenceUnitName = persistenceUnitName;
        this.dataSourceName = dataSourceName;
        this.multiTenancyStrategy = multiTenancyStrategy;
    }

    @Override
    public ConnectionProvider resolve(String tenantId) {
        LOG.debugv("resolve((persistenceUnitName={0}, tenantIdentifier={1})", persistenceUnitName, tenantId);
        LOG.debugv("multitenancy strategy: {0}", multiTenancyStrategy);

        AgroalDataSource dataSource = tenantDataSource(dataSourceName, tenantId, multiTenancyStrategy);
        if (dataSource == null) {
            throw new IllegalStateException(
                    String.format(Locale.ROOT, "No instance of datasource found for persistence unit '%1$s' and tenant '%2$s'",
                            persistenceUnitName, tenantId));
        }
        return switch (multiTenancyStrategy) {
            case DATABASE -> new QuarkusConnectionProvider(dataSource);
            case SCHEMA -> new SchemaTenantConnectionProvider(tenantId, dataSource);
            default -> throw new IllegalStateException("Unexpected multitenancy strategy: " + multiTenancyStrategy);
        };
    }

    private static AgroalDataSource tenantDataSource(Optional<String> dataSourceName, String tenantId,
            MultiTenancyStrategy strategy) {
        return switch (strategy) {
            case DATABASE -> Arc.container().instance(AgroalDataSource.class, new DataSource.DataSourceLiteral(tenantId)).get();
            // The datasource name should always be present when using a multi-tenancy other than DATABASE;
            // we perform checks in HibernateOrmProcessor during the build.
            case SCHEMA -> getDataSource(dataSourceName.get());
            default -> throw new IllegalStateException("Unexpected multitenancy strategy: " + strategy);

View on GitHub (pinned to e1c734241f)

Solutions

Define the missing datasource in application.properties, e.g. quarkus.datasource."<tenantId>".jdbc.url=...
Make TenantResolver.resolveTenantId() return ids that exactly match configured datasource names
Verify the persistence unit's datasource name (quarkus.hibernate-orm.datasource) and strategy configuration align with the tenant datasources
Check build-time validation config for multitenancy (quarkus.hibernate-orm.multitenant) matches the strategy used

Example fix

// before: TenantResolver returns "acme" but no datasource named acme
// after (application.properties)
quarkus.datasource."acme".db-kind=postgresql
quarkus.datasource."acme".jdbc.url=jdbc:postgresql://localhost:5432/acme
quarkus.datasource."acme".username=user
quarkus.datasource."acme".password=pass

Defensive patterns

Strategy: validation

Validate before calling

AgroalDataSource ds = Arc.container().instance(AgroalDataSource.class,
        AgroalDataSourceUtil.qualifier(tenantId)).get();
if (ds == null) {
    throw new IllegalStateException("No datasource configured for tenant " + tenantId
        + " — check quarkus.datasource.\"" + tenantId + "\".*");
}

Type guard

Optional<AgroalDataSource> lookupTenantDs(String tenantId) {
    return Optional.ofNullable(Arc.container().instance(AgroalDataSource.class,
        AgroalDataSourceUtil.qualifier(tenantId)).get());
}

Try / catch

try {
    ConnectionProvider cp = resolver.resolve(tenantId);
} catch (IllegalStateException e) {
    Log.errorf("Datasource missing for PU=%s tenant=%s", pu, tenantId);
    throw new WebApplicationException("Unknown tenant", 400);
}

Prevention

Define one quarkus.datasource."<tenantId>" block per tenant
Keep TenantResolver tenant ids in sync with datasource names (add an automated test)
Validate multitenancy config at startup with a smoke resolution of all tenants

When it happens

Trigger: At runtime on tenant resolution: the datasource named for the tenant (or per-strategy lookup) doesn't exist — wrong quarkus.datasource.<name> config, datasource not defined for a DATABASE-strategy tenant id, tenant id mismatch (case/typos) with a configured datasource name, or multiTenancyStrategy CONFIGURATION without matching datasource beans.

Common situations: Missing quarkus.datasource."tenant1".jdbc.url config; TenantResolver producing tenant ids that don't match datasource names; renaming datasources without updating the tenant mapping; using SCHEMA strategy without the required named datasource configured.

Related errors

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