quarkusio/quarkus · error · IllegalStateException

@PersistenceUnit annotations are not supported at the class

Error message

@PersistenceUnit annotations are not supported at the class level on model classes:
	- %s
Use the `.packages` configuration property or package-level annotations instead.

What it means

The @jakarta.persistence.PersistenceUnit (and related) annotations may only be applied at package level (or via the quarkus.hibernate-orm."<pu>".packages config) to partition model classes into persistence units. Applying them at the class level on model classes is unsupported, and the processor fails with an IllegalStateException listing the offending classes.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java:1413

            boolean isEntity = jpaModel.getEntityClassNames().contains(className);
            // Even if persistenceUnits is empty, the class is still assigned (to nothing)
            if (isEntity) {
                assignedEntityClassNames.add(className);
            }
            assignedModelClassAndPackageNames.add(className);
            for (String persistenceUnitName : persistenceUnits) {
                var model = modelPerPersistenceUnit.computeIfAbsent(persistenceUnitName,
                        ignored -> new JpaPersistenceUnitModel());

                if (isEntity) {
                    model.entityClassNames().add(className);
                }
                model.allModelClassAndPackageNames().add(className);
            }
        }

        if (!modelClassesWithPersistenceUnitAnnotations.isEmpty()) {
            throw new IllegalStateException(String.format(Locale.ROOT,
                    "@PersistenceUnit annotations are not supported at the class level on model classes:\n\t- %s\nUse the `.packages` configuration property or package-level annotations instead.",
                    String.join("\n\t- ", modelClassesWithPersistenceUnitAnnotations)));
        }

        for (String modelPackageName : jpaModel.getAllModelPackageNames()) {
            // Package rules keys are "normalized" package names, so we want to normalize the package on lookup:
            Set<String> persistenceUnitNames = packageRules.get(normalizePackage(modelPackageName));
            if (persistenceUnitNames == null) {
                continue;
            }
            for (String persistenceUnitName : persistenceUnitNames) {
                var model = modelPerPersistenceUnit.computeIfAbsent(persistenceUnitName,
                        ignored -> new JpaPersistenceUnitModel());
                model.allModelClassAndPackageNames().add(modelPackageName);
            }
        }

        // Copy xmlMappings, so that consumers of JpaModelPerPersistenceUnitBuildItem

View on GitHub (pinned to e1c734241f)

Solutions

1. Move the annotation to package-info.java (package-level) covering those classes, or remove it and use quarkus.hibernate-orm."<pu>".packages to assign classes to the PU
2. Remove class-level @PersistenceUnit annotations entirely if only one PU is used

Example fix

// before: User.java
@PersistenceUnit("audit")
@Entity public class User {...}
// after: package-info.java in the entity package
@PersistenceUnit("audit")
package com.acme.entities;

// Ensure @PersistenceUnit appears only on package-info.java, never on entity classes:
for (Class<?> e : List.of(User.class)) {
    if (e.isAnnotationPresent(jakarta.persistence.PersistenceUnit.class)) {
        throw new IllegalStateException("@PersistenceUnit not allowed at class level: " + e);
    }
}

When it happens

Trigger: During JPA model partitioning in HibernateOrmProcessor, modelClassesWithPersistenceUnitAnnotations is non-empty because one or more @Entity/@MappedSuperclass classes carry a class-level @PersistenceUnit-style annotation.

Common situations: Annotating individual entity classes with @PersistenceUnit hoping to route them to a named PU; converting package-info.java annotations to class annotations during refactoring.

Related errors

• Unable to find an EntityManagerFactory for persistence unit
• Methods that are annotated with JPA Listener annotations sho
• An extension attempted to contribute the default persistence
• Persistence unit '%s' is contributed by an extension but is
• Multiple ${AdditionalPersistenceUnitBuildItem} for persisten

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