{"record":{"id":"9706d43e3b8f4efc","repo":"hibernate/hibernate-orm","slug":"mappedsuperclasstype-cannot-be-used-to-create-an-s","errorCode":null,"errorMessage":"MappedSuperclassType cannot be used to create an SqmPath - that would be an SqmFrom which are created directly","messagePattern":"MappedSuperclassType cannot be used to create an SqmPath - that would be an SqmFrom which are created directly","errorType":"exception","errorClass":"UnsupportedMappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappedSuperclassTypeImpl.java","lineNumber":147,"sourceCode":"\t@Nonnull\n\tpublic BindableType getBindableType() {\n\t\treturn ENTITY_TYPE;\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic PersistenceType getPersistenceType() {\n\t\treturn MAPPED_SUPERCLASS;\n\t}\n\n\t@Override\n\tprotected boolean isIdMappingRequired() {\n\t\treturn false;\n\t}\n\n\t@Override\n\tpublic SqmPath<J> createSqmPath(SqmPath<?> lhs, @Nullable SqmPathSource<?> intermediatePathSource) {\n\t\tthrow new UnsupportedMappingException(\n\t\t\t\t\"MappedSuperclassType cannot be used to create an SqmPath - that would be an SqmFrom which are created directly\"\n\t\t);\n\t}\n}\n","sourceCodeStart":129,"sourceCodeEnd":152,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/MappedSuperclassTypeImpl.java#L129-L152","documentation":"MappedSuperclassTypeImpl.createSqmPath unconditionally throws UnsupportedMappingException: a @MappedSuperclass domain type can never be the source of an SqmPath, because SQM paths must grow from an SqmFrom (an entity root or join). It is a hard API contract, not a runtime state check.","triggerScenarios":"Attempting to build an SQM path whose path source is a mapped superclass type — e.g. via JpaMetamodel.managedType(...) then createSqmPath, treat()/as() targeting a @MappedSuperclass-typed expression, or a custom criteria/QueryEngine extension walking attributes whose declaring type is a mapped superclass without an entity lhs.","commonSituations":"Porting code where the base class used to be an @Entity; trying to write polymorphic queries against a shared @MappedSuperclass (e.g. a common 'BaseEntity' with id/version); generic repositories that accept the mapped-superclass class literal as the domain type.","solutions":["Make the shared base class an @Entity with an @Inheritance strategy instead of @MappedSuperclass when it must be a query root","Query a concrete @Entity subclass (or any subclass — Hibernate folds in siblings via polymorphism) instead of the mapped superclass","In generic repository code, constrain/receive the entity class rather than the mapped-superclass class"],"exampleFix":"// before\n@MappedSuperclass\npublic abstract class BaseEntity { @Id Long id; }\n// query against the superclass\nem.createQuery(\"select b from BaseEntity b\", BaseEntity.class); // path/root resolution fails\n\n// after\n@Entity @Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)\npublic abstract class BaseEntity { @Id Long id; }\n// now a valid polymorphic root","handlingStrategy":"type-guard","validationCode":"// Reject mapped-superclass query domains before touching SQM\nif (domainClass.isAnnotationPresent(jakarta.persistence.MappedSuperclass.class)) {\n  throw new IllegalArgumentException(\n      domainClass.getName() + \" is a @MappedSuperclass and cannot be a query root; query a concrete @Entity subclass\");\n}","typeGuard":"static boolean isQueryableType(Metamodel metamodel, Class<?> cls) {\n  if (!cls.isAnnotationPresent(jakarta.persistence.Entity.class)\n      && !cls.isAnnotationPresent(jakarta.persistence.MappedSuperclass.class)) {\n    return false;\n  }\n  try {\n    metamodel.managedType(cls);\n    return !cls.isAnnotationPresent(jakarta.persistence.MappedSuperclass.class)\n        || metamodel.getEntities().stream().anyMatch(e -> cls.isAssignableFrom(e.getJavaType()));\n  } catch (IllegalArgumentException e) {\n    return false;\n  }\n}","tryCatchPattern":null,"preventionTips":["Never use @MappedSuperclass classes as query roots, HQL entity names, or graph targets — only concrete @Entity types","In shared base repositories, accept the concrete entity class (or Class<? extends BaseEntity> resolved per entity)","Model polymorphic hierarchies with @Entity + @Inheritance, reserving @MappedSuperclass for state reuse only"],"tags":["hibernate","jpa","mapped-superclass","sqm","criteria-api"],"backgroundTag":"query-non-entity-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}