quarkusio/quarkus · error · IllegalStateException

PanacheEntity '%s' cannot be defined for usage in several pe

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.

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)

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.