{"record":{"id":"262eb687b94ca9bd","repo":"hibernate/hibernate-orm","slug":"mapped-superclass-may-not-specify-an-inheri","errorCode":null,"errorMessage":"Mapped superclass '{}' may not specify an '@Inheritance' mapping strategy","messagePattern":"Mapped superclass '(.+?)' may not specify an '@Inheritance' mapping strategy","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/AnnotationBinder.java","lineNumber":295,"sourceCode":"\t\t\tfinal String name = unqualify( qualifiedName );\n\t\t\tfinal String rename = annotatedClass.getDirectAnnotationUsage( Imported.class ).rename();\n\t\t\tcontext.getMetadataCollector().addImport( rename.isBlank() ? name : rename, qualifiedName );\n\t\t}\n\t}\n\n\tprivate static void detectMappedSuperclassProblems(ClassDetails annotatedClass) {\n\t\tif ( isMappedSuperclass( annotatedClass ) ) {\n\t\t\t// @Entity and @MappedSuperclass on the same class leads to NPE down the road\n\t\t\tif ( isEntity( annotatedClass ) ) {\n\t\t\t\tthrow new AnnotationException( \"Type '\" + annotatedClass.getName()\n\t\t\t\t\t\t+ \"' is annotated both '@Entity' and '@MappedSuperclass'\" );\n\t\t\t}\n\t\t\tif ( annotatedClass.hasDirectAnnotationUsage( Table.class ) ) {\n\t\t\t\tthrow new AnnotationException( \"Mapped superclass '\" + annotatedClass.getName()\n\t\t\t\t\t\t+ \"' may not specify a '@Table'\" );\n\t\t\t}\n\t\t\tif ( annotatedClass.hasDirectAnnotationUsage( Inheritance.class ) ) {\n\t\t\t\tthrow new AnnotationException( \"Mapped superclass '\" + annotatedClass.getName()\n\t\t\t\t\t\t+ \"' may not specify an '@Inheritance' mapping strategy\" );\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static void bindTypeDescriptorRegistrations(\n\t\t\tAnnotationTarget annotatedElement,\n\t\t\tMetadataBuildingContext context) {\n\t\tfinal var managedBeanRegistry = context.getBootstrapContext().getManagedBeanRegistry();\n\t\tfinal var sourceModelContext = modelsContext( context );\n\n\t\tannotatedElement.forEachAnnotationUsage(\n\t\t\t\tJavaTypeRegistration.class,\n\t\t\t\tsourceModelContext,\n\t\t\t\tusage -> handleJavaTypeRegistration( context, managedBeanRegistry, usage )\n\t\t);\n\n\t\tannotatedElement.forEachAnnotationUsage(","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/AnnotationBinder.java#L277-L313","documentation":"A '@MappedSuperclass' declares a direct '@Inheritance' annotation. Inheritance strategies (SINGLE_TABLE, JOINED, TABLE_PER_CLASS) are per-hierarchy and belong on the root '@Entity' of the hierarchy; a mapped superclass is not part of that decision, so Hibernate rejects the annotation.","triggerScenarios":"'@MappedSuperclass @Inheritance(strategy = InheritanceType.JOINED)' on an abstract base; pulling a root entity's annotations up while converting it to a superclass; copy-pasting a full annotation set onto a new base class.","commonSituations":"Reorganizing class hierarchies and moving @Inheritance 'for reuse'; mixing @MappedSuperclass chains with @Entity inheritance chains in the same codebase.","solutions":["Remove '@Inheritance' from the mapped superclass.","Put '@Inheritance(strategy = ...)' on the ROOT @Entity of the hierarchy that each concrete subclass extends.","If the base class must carry the strategy, make it an '@Entity' root instead of a '@MappedSuperclass'."],"exampleFix":"// before\n@MappedSuperclass\n@Inheritance(strategy = InheritanceType.JOINED) // -> error\npublic abstract class BaseThing { @Id Long id; }\n\n// after\n@MappedSuperclass\npublic abstract class BaseThing { @Id Long id; }\n\n@Entity\n@Inheritance(strategy = InheritanceType.JOINED)\npublic abstract class Thing extends BaseThing { ... }","handlingStrategy":"validation","validationCode":"// Guard: mapped superclasses must not declare @Inheritance\nif (cls.isAnnotationPresent(MappedSuperclass.class)\n        && cls.isAnnotationPresent(Inheritance.class)) {\n    throw new IllegalStateException(\n        cls.getName() + \": @MappedSuperclass may not declare @Inheritance\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Metadata md = sources.buildMetadata();\n} catch (AnnotationException e) {\n    // 'may not specify an @Inheritance mapping strategy' -> move @Inheritance\n    // to the root @Entity of the hierarchy\n    throw newConfigurationException(\"Illegal @Inheritance on superclass\", e);\n}","preventionTips":["Declare @Inheritance exactly once, on the root @Entity of each hierarchy.","Do not copy full root-entity annotation sets onto new superclasses."],"tags":["hibernate","jpa","mapped-superclass","inheritance","orm-mapping"],"backgroundTag":"mapped-superclass-misuse","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}