quarkusio/quarkus · error · IllegalStateException

entities do not support being attached to several persisten

Error message

 entities do not support being attached to several persistence units:

What it means

The Hibernate ORM Panache deployment validates that each entity is associated with exactly one persistence unit. determineEntityPersistenceUnits collects entity-to-PU mappings, and when an entity appears in more than one persistence unit (violatingEntities non-empty) it builds a message and throws IllegalStateException. (Note: the throw sits inside the loop, so it aborts on the first violating entity.)

Source

Thrown at extensions/panache/hibernate-orm-panache/deployment/src/main/java/io/quarkus/hibernate/orm/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. Scope each entity to a single persistence unit by restricting the packages scanned per PU (quarkus.hibernate-orm."pu".packages)
  2. Remove duplicate persistence-unit definitions or exclude shared entities from one of them
  3. Move entities only used by one datasource into a dedicated package and configure each PU's packages accordingly

Example fix

// before: both PUs scan the same package
quarkus.hibernate-orm.pu1.packages=com.example.entity
quarkus.hibernate-orm.pu2.packages=com.example.entity
// after: split packages
quarkus.hibernate-orm.pu1.packages=com.example.entity.first
quarkus.hibernate-orm.pu2.packages=com.example.entity.second
Defensive patterns

Strategy: validation

Validate before calling

// before build, ensure no entity package is scanned by two PUs
Map<String, List<String>> entityToPus = collectEntityPus(config); // from your build step
List<String> violations = entityToPus.entrySet().stream()
        .filter(e -> e.getValue().size() > 1)
        .map(e -> e.getKey() + " -> " + e.getValue())
        .toList();
if (!violations.isEmpty()) throw new IllegalStateException("Entities in multiple PUs: " + violations);

Try / catch

try {
    determineEntityPersistenceUnits(...);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("several persistence units")) {
        throw new IllegalStateException("Restrict each entity package to one quarkus.hibernate-orm.<pu>.packages", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: A @Entity managed by Panache is resolvable under two persistence units defined in quarkus.datasource.* / quarkus.hibernate-orm.* configs — e.g. two <persistence-unit> definitions or two named Hibernate ORM configs both scanning the same entity packages.

Common situations: Multi-datasource setups where entity classes are in a package scanned by both persistence units; forgetting to restrict entities per PU; sharing an entity jar across two Quarkus Hibernate ORM configurations.

Related errors

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