quarkusio/quarkus · critical · IllegalStateException

No instance of %1$s was found for persistence unit %2$s. You

Error message

No instance of %1$s was found for persistence unit %2$s. You need to create an implementation for this interface to allow resolving the current tenant connection.

What it means

For multi-tenant Hibernate ORM, each tenant connection is obtained from a CDI bean implementing TenantConnectionResolver. This error is thrown when no such bean is registered for the persistence unit, so HibernateMultiTenantConnectionProvider cannot resolve a ConnectionProvider.

Source

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

        if (provider == null) {
            final ConnectionProvider connectionProvider = resolveConnectionProvider(persistenceUnitName, tenantIdentifier);
            providerMap.put(tenantIdentifier, connectionProvider);
            return connectionProvider;
        }
        return provider;

    }

    private static ConnectionProvider resolveConnectionProvider(String persistenceUnitName, String tenantIdentifier) {
        LOG.debugv("resolveConnectionProvider(persistenceUnitName={0}, tenantIdentifier={1})", persistenceUnitName,
                tenantIdentifier);
        // TODO when we switch to the non-legacy method, don't forget to update the definition of the default bean
        //   of type DataSourceTenantConnectionResolver (add the @PersistenceUnitExtension qualifier to that bean)
        InjectableInstance<TenantConnectionResolver> instance = PersistenceUnitUtil
                .legacySingleExtensionInstanceForPersistenceUnit(
                        TenantConnectionResolver.class, persistenceUnitName);
        if (instance.isUnsatisfied()) {
            throw new IllegalStateException(
                    String.format(
                            Locale.ROOT, "No instance of %1$s was found for persistence unit %2$s. "
                                    + "You need to create an implementation for this interface to allow resolving the current tenant connection.",
                            TenantConnectionResolver.class.getSimpleName(), persistenceUnitName));
        }
        TenantConnectionResolver resolver = instance.get();
        ConnectionProvider cp = resolver.resolve(tenantIdentifier);
        if (cp == null) {
            throw new IllegalStateException("Method 'TenantConnectionResolver."
                    + "resolve(String)' returned a null value. This violates the contract of the interface!");
        }
        return cp;
    }

    /**
     * Retrieves the tenant resolver or fails if it is not available.
     *
     * @return Current tenant resolver.

View on GitHub (pinned to e1c734241f)

Solutions

1. Implement TenantConnectionResolver (e.g., extend DatabaseTenantConnectionResolver or SchemaTenantConnectionResolver) as a CDI bean
2. Annotate the bean with @PersistenceUnitExtension so it's linked to the persistence unit
3. Ensure each tenant has a corresponding configured datasource if using database-per-tenant
4. Confirm the bean archive includes the implementation (has a bean-defining annotation)

Example fix

// before
// no TenantConnectionResolver bean -> IllegalStateException

// after
@PersistenceUnitExtension
@ApplicationScoped
public class MyConnectionResolver implements TenantConnectionResolver {
    @Override
    public ConnectionProvider resolve(String tenantId) {
        return databaseResolverFor(tenantId);
    }
}

boolean hasConnectionResolver = !Arc.container()
    .instance(TenantConnectionResolver.class).isUnsatisfied();
if (multiTenancyEnabled && !hasConnectionResolver) throw new IllegalStateException("Register a TenantConnectionResolver");

boolean connectionResolverPresent() {
    return Arc.container() != null
        && Arc.container().instance(TenantConnectionResolver.class).isResolvable();
}

try {
    return em.unwrap(SessionImplementor.class).getSessionFactory();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("TenantConnectionResolver")) { failFast("Missing connection resolver"); }
    throw e;
}

When it happens

Trigger: quarkus.hibernate.orm.multi_tenancy.enabled=true and an operation needs a tenant connection, but no @PersistenceUnitExtension bean implementing TenantConnectionResolver exists for the persistence unit; HibernateMultiTenantConnectionProvider.resolveConnectionProvider finds the CDI instance unsatisfied.

Common situations: Enabling multi-tenancy without a connection resolver; forgetting @PersistenceUnitExtension on the implementation; resolver bean defined in a library without bean discovery; typical with quarkus.hibernate.orm.datasource + DatabaseTenantConnectionResolver misuse (e.g., not exposing a bean for a schema-based strategy).

Related errors

• No instance of %1$s was found for persistence unit %2$s. You
• No instance of %1$s was found for persistence unit %2$s. You
• This PersistenceProvider does not support createEntityManage
• Multiple instances of %1$s were found for persistence unit %
• Cannot use the EntityManager/Session because neither a trans

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