{"record":{"id":"7c07b7ed5cec1e16","repo":"hibernate/hibernate-orm","slug":"mappedsuperclasstypename-is-not-a-supertype-of","errorCode":null,"errorMessage":"{mappedSuperclassTypeName} is not a supertype of {componentTypeName}","messagePattern":"(.+?) is not a supertype of (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/internal/MetadataContext.java","lineNumber":619,"sourceCode":"\t\t\t\tgetJavaTypeRegistry().resolveManagedTypeDescriptor( componentClass ),\n\t\t\t\tgetMappedSuperclassDomainType( idClassComponent, componentClass ),\n\t\t\t\tnull,\n\t\t\t\tfalse,\n\t\t\t\tgetJpaMetamodel()\n\t\t);\n\t}\n\n\tprivate <Y> MappedSuperclassDomainType<? super Y> getMappedSuperclassDomainType(\n\t\t\tComponent idClassComponent, Class<Y> componentClass) {\n\t\tfinal var mappedSuperclass = idClassComponent.getMappedSuperclass();\n\t\tif ( mappedSuperclass == null ) {\n\t\t\treturn null;\n\t\t}\n\t\telse {\n\t\t\tfinal var domainType = locateMappedSuperclassType( mappedSuperclass );\n\t\t\tfinal var mappedSuperclassClass = domainType.getJavaType();\n\t\t\tif ( !mappedSuperclassClass.isAssignableFrom( componentClass ) ) {\n\t\t\t\tthrow new IllegalStateException(\n\t\t\t\t\t\tmappedSuperclassClass.getTypeName()\n\t\t\t\t\t\t+ \" is not a supertype of \" + componentClass.getTypeName()\n\t\t\t\t);\n\t\t\t}\n\t\t\t@SuppressWarnings(\"unchecked\") // Safe, we just checked\n\t\t\tfinal var castDomainType = (MappedSuperclassDomainType<? super Y>) domainType;\n\t\t\treturn castDomainType;\n\t\t}\n\t}\n\n\tprivate <X> void applyIdMetadata(MappedSuperclass mappingType, MappedSuperclassDomainType<X> jpaMappingType) {\n\t\tfinal var managedType = (ManagedDomainType<X>) jpaMappingType;\n\t\tfinal var attributeContainer = (AttributeContainer<X>) managedType;\n\t\tif ( mappingType.hasIdentifierProperty() ) {\n\t\t\tfinal var declaredIdentifierProperty = mappingType.getDeclaredIdentifierProperty();\n\t\t\tif ( declaredIdentifierProperty != null ) {\n\t\t\t\tfinal var attribute =\n\t\t\t\t\t\t(SingularPersistentAttribute<X, ?>)","sourceCodeStart":601,"sourceCodeEnd":637,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/internal/MetadataContext.java#L601-L637","documentation":"An IllegalStateException thrown by MetadataContext.getMappedSuperclassDomainType while processing @IdClass mappings: when an entity's id class component declares a MappedSuperclass, Hibernate resolves its domain type and verifies that the mapped-superclass Java type is actually assignable from the id class (mappedSuperclassClass.isAssignableFrom(componentClass)). If the @IdClass type does not sit below the mapped superclass that provided the id fields, the invariant is broken and JPA metamodel building fails with 'X is not a supertype of Y'.","triggerScenarios":"An @IdClass whose class does not extend the @MappedSuperclass that declares the id attributes (e.g. a generic base @MappedSuperclass 'BaseEntity<T>' declares the id, but the @IdClass only re-declares fields instead of extending the same base); hierarchy refactors where entity inheritance and id-class inheritance were not kept parallel; mixed annotation/XML setups re-declaring the same id fields inconsistently.","commonSituations":"Generic repository base classes (@MappedSuperclass with @Id field) combined with @IdClass that duplicates the field instead of extending the base; upgrading Hibernate 5.x projects where this mismatch previously went unchecked; multi-module projects where the id class hierarchy diverged from the entity hierarchy.","solutions":["Make the @IdClass extend the same @MappedSuperclass (or otherwise be a subtype of it) that declares the id attributes","Alternatively, move the id declarations out of the mapped superclass into each entity (or the id class) so no cross-hierarchy assignability is required","Consider @EmbeddedId instead of @IdClass - it avoids the superclass/id-class alignment requirement entirely","After fixing, rebuild the metamodel at startup (EntityManagerFactory creation) to confirm the invariant holds"],"exampleFix":"// before - IdClass does not extend the mapped superclass that owns the id\n@MappedSuperclass\npublic abstract class BaseEntity { @Id Long id; }\n\n@Entity\n@IdClass(UserId.class)          // UserId only re-declares id\npublic class User extends BaseEntity { ... }\n\npublic class UserId implements Serializable { Long id; }\n\n// after - align the hierarchies (or switch to @EmbeddedId)\npublic class UserId extends BaseEntity implements Serializable {}\n\n// or avoid @IdClass entirely\n@Entity\npublic class User extends BaseEntity { @EmbeddedId EmbeddedUserId id; }","handlingStrategy":"validation","validationCode":"// Verify the @IdClass hierarchy aligns with the @MappedSuperclass that owns the id\nClass<?> idClass = UserId.class;\nClass<?> idOwningSuperclass = BaseEntity.class; // declared @MappedSuperclass carrying @Id\nif ( !idOwningSuperclass.isAssignableFrom(idClass) ) {\n    throw new IllegalStateException(idClass + \" must extend \" + idOwningSuperclass + \" (id-class hierarchy mismatch)\");\n}","typeGuard":"static boolean idClassHierarchyAligned(Class<?> mappedSuperclass, Class<?> idClass) {\n    return mappedSuperclass == null || mappedSuperclass.isAssignableFrom(idClass);\n}","tryCatchPattern":"try {\n    EntityManagerFactory emf = Persistence.createEntityManagerFactory(\"pu\");\n}\ncatch ( IllegalStateException e ) {\n    if ( e.getMessage() != null && e.getMessage().endsWith(\"is not a supertype of\") ) {\n        throw new ConfigurationError(\"@IdClass must sit below the @MappedSuperclass that declares the id - \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Keep @IdClass inheritance parallel to entity @MappedSuperclass inheritance","Consider @EmbeddedId to avoid id-class/superclass alignment constraints altogether","After any hierarchy refactor, boot the persistence unit in a unit test"],"tags":["hibernate","jpa","idclass","mapped-superclass","inheritance","metamodel"],"backgroundTag":"idclass-hierarchy-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}