quarkusio/quarkus · error · IllegalStateException

%s entities do not support being attached to several persist

Error message

%s entities do not support being attached to several persistence units:
	- %s is attached to: %s

What it means

EntityToPersistenceUnitUtil.determineEntityPersistenceUnits validates at build time that each Panache (Reactive) entity maps to exactly one persistence unit. If an entity is found on several PUs, it throws IllegalStateException listing the entity and its PUs, because multi-PU entity attachment is unsupported.

Source

Thrown at extensions/panache/hibernate-reactive-panache/deployment/src/main/java/io/quarkus/hibernate/reactive/panache/deployment/EntityToPersistenceUnitUtil.java:56

            if (!isCandidate) {
                continue;
            }

            if (selectedPersistenceUnits.size() == 1) {
                result.put(entityName, selectedPersistenceUnits.iterator().next());
            } else {
                violatingEntities.put(entityName, selectedPersistenceUnits);
            }
        }

        if (violatingEntities.size() > 0) {
            StringBuilder message = new StringBuilder(
                    String.format("%s entities do not support being attached to several persistence units:\n", source));
            for (Map.Entry<String, Set<String>> violatingEntityEntry : violatingEntities
                    .entrySet()) {
                message.append("\t- ").append(violatingEntityEntry.getKey()).append(" is attached to: ")
                        .append(String.join(",", violatingEntityEntry.getValue()));
                throw new IllegalStateException(message.toString());
            }
        }

        return result;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Configure each PU to scan/include only disjoint entity packages (quarkus.hibernate-orm."pu".packages)
2. Remove duplicate entity inclusions from one of the persistence units
3. Give the shared entity to exactly one PU and reference others via their own entities

Example fix

// before
quarkus.hibernate-orm.pu1.packages=org.acme.model
quarkus.hibernate-orm.pu2.packages=org.acme.model
// after
quarkus.hibernate-orm.pu1.packages=org.acme.model.a
quarkus.hibernate-orm.pu2.packages=org.acme.model.b

Set<String> pus = entitiesByPu().get(entityClass.getName());
if (pus != null && pus.size() > 1)
    throw new IllegalStateException(entityClass + " attached to multiple persistence units: " + pus);

When it happens

Trigger: quarkus.hibernate-orm (reactive).persistence-units.<pu> scan-for-entities or explicit entity class lists including the same @Entity class in more than one persistence unit.

Common situations: Two named persistence units both configured to package-scan the same model package; copying entities into a shared package after splitting into multiple PUs; enabling 'scan-for-entities' on several PUs in one app.

Related errors

• Entity '%s' was not found. Did you forget to annotate your P
• PanacheEntity '%s' cannot be defined for usage in several pe
• Attempting to boot a deactivated Hibernate Reactive persiste
• Mutiny.SessionFactory bean not found
• entities do not support being attached to several persisten

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