quarkusio/quarkus · error · IllegalStateException

PanacheEntity ' ' cannot be defined for usage in several…

Error message

PanacheEntity '%s' cannot be defined for usage in several persistence units which is not supported. The following persistence units were found: %s.

What it means

At deployment, Kotlin Panache collects which persistence units each PanacheEntity is used with. PanacheEntity subclasses carry a hard-wired persistence unit reference, so an entity assigned to more than one persistence unit is unsupported and the build fails with IllegalStateException listing the conflicting units.

Solutions

Make the entity extend PanacheEntityBase instead and manage persistence with an injected EntityManager, or use the active-entity pattern per unit.
Configure disjoint packages/classes per persistence unit so each PanacheEntity belongs to exactly one (quarkus.hibernate-orm.<name>.packages).
Split the shared entity into one subclass per persistence unit.
Review the listed persistence unit names in the message and remove the duplicate mapping.

Example fix

// before
class Customer : PanacheEntity() // mapped by both 'default' and 'audit' PUs -> build fails

// after
@ApplicationScoped
class AuditCustomerRepository { // per-PU repository instead of shared PanacheEntity
    fun find(id: Long): Customer? =
        withEntityManager("audit") { it.find(Customer::class.java, id) }
}

Defensive patterns

Strategy: validation

Validate before calling

// build-time check: ensure each PanacheEntity package is mapped by exactly one PU
Set<String> pus = persistenceUnitsFor(entityClass);
if (pus.size() > 1) {
    throw new IllegalStateException("Entity " + entityClass + " mapped by multiple PUs: " + pus);
}

Try / catch

// Deployment-time failure; cannot be caught at runtime.
// Fix configuration; optionally assert in build scripts:
// fail build if entityPackages sets of all quarkus.hibernate-orm.<pu>.packages intersect

Prevention

Give each persistence unit disjoint packages in quarkus.hibernate-orm.<name>.packages.
Extend PanacheEntityBase and use repositories when an entity must serve multiple units.
Audit persistence unit config after adding a new named PU.
Run the build (not just tests) to surface deployment-time violations early.

When it happens

Trigger: A class extending PanacheEntity (or KotlinPanacheEntity) being referenced/annotated for multiple persistence units in quarkus.hibernate-orm.* config (e.g. an entity package or class mapped by two named persistence units).

Common situations: Multi-tenancy or multi-database setups where packages are included in several persistence unit configurations; copy-pasted persistence unit configs overlapping in their entity packages.

Related errors

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

Appendix: source

Thrown at extensions/panache/hibernate-orm-panache-kotlin/deployment/src/main/java/io/quarkus/hibernate/orm/panache/kotlin/deployment/KotlinPanacheResourceProcessor.java:163

        Map<String, Set<String>> collectedEntityToPersistenceUnits;
        boolean incomplete;
        if (jpaModelPersistenceUnitMapping.isPresent()) {
            collectedEntityToPersistenceUnits = jpaModelPersistenceUnitMapping.get().getEntityToPersistenceUnits();
            incomplete = jpaModelPersistenceUnitMapping.get().isIncomplete();
        } else {
            collectedEntityToPersistenceUnits = new HashMap<>();
            // This happens if there is no persistence unit, in which case we definitely know this metadata is complete.
            incomplete = false;
        }

        Map<String, String> panacheEntityToPersistenceUnit = new HashMap<>();
        for (Map.Entry<String, Set<String>> entry : collectedEntityToPersistenceUnits.entrySet()) {
            String entityName = entry.getKey();
            List<String> selectedPersistenceUnits = new ArrayList<>(entry.getValue());
            boolean isPanacheEntity = modelClasses.contains(entityName);
            if (selectedPersistenceUnits.size() > 1 && isPanacheEntity) {
                throw new IllegalStateException(String.format(
                        "PanacheEntity '%s' cannot be defined for usage in several persistence units which is not supported. The following persistence units were found: %s.",
                        entityName, String.join(",", selectedPersistenceUnits)));
            }

            panacheEntityToPersistenceUnit.put(entityName, selectedPersistenceUnits.get(0));
        }
        // This is called even if there are no entity types, so that Panache gets properly initialized.
        recorder.addEntityTypesToPersistenceUnit(panacheEntityToPersistenceUnit, incomplete);
    }

    private void processRepositories(CombinedIndexBuildItem index,
            BuildProducer<BytecodeTransformerBuildItem> transformers,
            List<String> classNamesToRegisterForReflection,
            PanacheRepositoryEnhancer enhancer,
            ByteCodeType baseType,
            ByteCodeType type) {

        Set<Type> typeParameters = new HashSet<>();

View on GitHub (pinned to e1c734241f)