{"record":{"id":"9ee383a55ace9e44","repo":"quarkusio/quarkus","slug":"persistenceunit-annotations-are-not-supported-at","errorCode":null,"errorMessage":"@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.","messagePattern":"@PersistenceUnit annotations are not supported at the class level on model classes:\n\t- (.+?)\nUse the `\\.packages` configuration property or package-level annotations instead\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java","lineNumber":1413,"sourceCode":"            boolean isEntity = jpaModel.getEntityClassNames().contains(className);\n            // Even if persistenceUnits is empty, the class is still assigned (to nothing)\n            if (isEntity) {\n                assignedEntityClassNames.add(className);\n            }\n            assignedModelClassAndPackageNames.add(className);\n            for (String persistenceUnitName : persistenceUnits) {\n                var model = modelPerPersistenceUnit.computeIfAbsent(persistenceUnitName,\n                        ignored -> new JpaPersistenceUnitModel());\n\n                if (isEntity) {\n                    model.entityClassNames().add(className);\n                }\n                model.allModelClassAndPackageNames().add(className);\n            }\n        }\n\n        if (!modelClassesWithPersistenceUnitAnnotations.isEmpty()) {\n            throw new IllegalStateException(String.format(Locale.ROOT,\n                    \"@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.\",\n                    String.join(\"\\n\\t- \", modelClassesWithPersistenceUnitAnnotations)));\n        }\n\n        for (String modelPackageName : jpaModel.getAllModelPackageNames()) {\n            // Package rules keys are \"normalized\" package names, so we want to normalize the package on lookup:\n            Set<String> persistenceUnitNames = packageRules.get(normalizePackage(modelPackageName));\n            if (persistenceUnitNames == null) {\n                continue;\n            }\n            for (String persistenceUnitName : persistenceUnitNames) {\n                var model = modelPerPersistenceUnit.computeIfAbsent(persistenceUnitName,\n                        ignored -> new JpaPersistenceUnitModel());\n                model.allModelClassAndPackageNames().add(modelPackageName);\n            }\n        }\n\n        // Copy xmlMappings, so that consumers of JpaModelPerPersistenceUnitBuildItem","sourceCodeStart":1395,"sourceCodeEnd":1431,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java#L1395-L1431","documentation":"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.","triggerScenarios":"During JPA model partitioning in HibernateOrmProcessor, modelClassesWithPersistenceUnitAnnotations is non-empty because one or more @Entity/@MappedSuperclass classes carry a class-level @PersistenceUnit-style annotation.","commonSituations":"Annotating individual entity classes with @PersistenceUnit hoping to route them to a named PU; converting package-info.java annotations to class annotations during refactoring.","solutions":["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","Remove class-level @PersistenceUnit annotations entirely if only one PU is used"],"exampleFix":"// before: User.java\n@PersistenceUnit(\"audit\")\n@Entity public class User {...}\n// after: package-info.java in the entity package\n@PersistenceUnit(\"audit\")\npackage com.acme.entities;","handlingStrategy":"validation","validationCode":"// Ensure @PersistenceUnit appears only on package-info.java, never on entity classes:\nfor (Class<?> e : List.of(User.class)) {\n    if (e.isAnnotationPresent(jakarta.persistence.PersistenceUnit.class)) {\n        throw new IllegalStateException(\"@PersistenceUnit not allowed at class level: \" + e);\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Apply @PersistenceUnit only in package-info.java","Use quarkus.hibernate-orm.\"<pu>\".packages config to assign classes to PUs instead of class annotations","Review refactors that move package-level annotations onto classes"],"tags":["jpa","persistence-unit","annotation-placement","hibernate-orm"],"backgroundTag":"unsupported-annotation-placement","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}