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 identifier.

What it means

When obtaining the current tenant identifier for a connection in a multi-tenant persistence unit, Quarkus looks up a TenantResolver CDI bean. This error mirrors error 990 but is raised from HibernateMultiTenantConnectionProvider.tenantResolver when the bean is missing, so the tenant id needed to select the connection provider cannot be determined.

Source

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

        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.
     */
    private static InstanceHandle<TenantResolver> tenantResolver(String persistenceUnitName) {
        InjectableInstance<TenantResolver> instance = PersistenceUnitUtil
                .legacySingleExtensionInstanceForPersistenceUnit(
                        TenantResolver.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 identifier.",
                    TenantResolver.class.getSimpleName(), persistenceUnitName));
        }

        return instance.getHandle();
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

Create a @PersistenceUnitExtension-annotated CDI bean implementing TenantResolver
Return a non-null default tenant id in getDefaultTenantId()
Disable multi_tenancy if multi-tenancy was not intended
Rebuild the application so CDI bean discovery picks up the new bean

Example fix

// before
quarkus.hibernate.orm.multi_tenancy.enabled=true
// (no TenantResolver bean defined)

// after
quarkus.hibernate.orm.multi_tenancy.enabled=true
// plus:
@PersistenceUnitExtension
@ApplicationScoped
public class HeaderTenantResolver implements TenantResolver {
    @Override
    public String getDefaultTenantId() { return "base"; }
}

Defensive patterns

Strategy: validation

Validate before calling

if (multiTenancyEnabled && !Arc.container().instance(TenantResolver.class).isResolvable()) {
    throw new IllegalStateException("TenantResolver bean required for multi-tenancy");
}

Type guard

boolean canResolveTenant(String puName) {
    return Arc.container() != null
        && Arc.container().instance(TenantResolver.class).isResolvable();
}

Try / catch

try {
    return emf.createEntityManager();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("resolving the current tenant identifier")) { failFast("Missing TenantResolver"); }
    throw e;
}

Prevention

Single source of truth: define TenantResolver once per persistence unit
Run an integration test that performs a tenant-scoped query at startup
Document the multi-tenancy bean contract in team guidelines

When it happens

Trigger: quarkus.hibernate.orm.multi_tenancy.enabled=true; HibernateMultiTenantConnectionProvider needs the tenant id (e.g., getAnyConnectionProvider or getConnectionProvider path) and PersistenceUnitUtil.legacySingleExtensionInstanceForPersistenceUnit(TenantResolver.class, ...) is unsatisfied for the persistence unit.

Common situations: Enabling multi-tenancy without implementing TenantResolver; forgetting @PersistenceUnitExtension; bean not discoverable by CDI; multiple deployments with per-PU beans where one PU lacks a resolver.

Related errors

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