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

When one Panache entity is collected as belonging to more than one persistence unit, the build step cannot decide which persistence unit it maps to; Kotlin Panache entities are tied to a single persistence unit. The processor throws at augmentation time.

Source

Thrown at extensions/panache/hibernate-reactive-panache-kotlin/deployment/src/main/java/io/quarkus/hibernate/reactive/panache/kotlin/deployment/HibernateReactivePanacheKotlinProcessor.java:135

        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 processCompanions(CombinedIndexBuildItem index, BuildProducer<BytecodeTransformerBuildItem> transformers,
            List<String> classNamesToRegisterForReflection,
            KotlinPanacheCompanionEnhancer enhancer) {

        Set<org.jboss.jandex.Type> typeParameters = new HashSet<>();
        for (ClassInfo classInfo : index.getComputingIndex()
                .getAllKnownImplementations(TYPE_BUNDLE.entityCompanionBase().dotName())) {
            if (classInfo.name().equals(TYPE_BUNDLE.entityCompanion().dotName())) {

View on GitHub (pinned to e1c734241f)

Solutions

Assign each Panache entity to exactly one persistence unit (configure per-PU entity packages or move the entity)
Convert the entity from Panache active-record style to a plain @Entity with EntityManager so it can be used across PUs
Restructure to one persistence unit if multi-PU isn't truly required

Example fix

// before (one entity, two PUs configured) -> fails
@Entity
public class Customer extends PanacheKotlinEntity
// after: split PUs so Customer belongs to only one,
// e.g. move entities to a package scoped to a single named PU

Defensive patterns

Strategy: validation

Validate before calling

var pus = configuredPersistenceUnitsFor(entityClass);
if (pus.size() > 1) throw new IllegalStateException("Entity " + entityClass + " maps to multiple PUs");

Try / catch

try { build } catch (IllegalStateException e) { if (e.getMessage().contains("several persistence units")) log.error("Reassign entity to one PU: {}", e.getMessage()); throw e; }

Prevention

Keep one Panache active-record entity per persistence unit
Use plain @Entity + EntityManager for shared entities
Document PU-to-package mapping

When it happens

Trigger: processEntities finds a class annotated as a Panache entity (modelClasses contains it) whose name appears in collectedEntityToPersistenceUnits with a set of more than one persistence unit.

Common situations: Configuring multiple persistence units (quarkus.hibernate-orm."pu1" and "pu2") and having a single @Entity extend PanacheEntity; entities not excluded from one PU via configuration.

Related errors

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