{"record":{"id":"095c662fba898315","repo":"hibernate/hibernate-orm","slug":"entity-class-classname-is-annotated-immutab","errorCode":null,"errorMessage":"Entity class '${className}' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy (only a root class may declare its mutability)","messagePattern":"Entity class '(.+?)' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy \\(only a root class may declare its mutability\\)","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java","lineNumber":1458,"sourceCode":"\t\tpersistentClass.setProxyInterfaceName( annotatedClass.getName() );\n\n\t\tif ( persistentClass instanceof RootClass ) {\n\t\t\tbindRootEntity();\n\t\t}\n\t\telse {\n\t\t\tcheckSubclassEntity();\n\t\t}\n\n\t\tensureNoMutabilityPlan();\n\n\t\tregisterImportName();\n\n\t\tprocessNamedEntityGraphs();\n\t}\n\n\tprivate void checkSubclassEntity() {\n\t\tif ( !isMutable() ) {\n\t\t\tthrow new AnnotationException( \"Entity class '\" + annotatedClass.getName()\n\t\t\t\t\t+ \"' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy\"\n\t\t\t\t\t+ \" (only a root class may declare its mutability)\" );\n\t\t}\n\t\tif ( isNotBlank( where ) ) {\n\t\t\tthrow new AnnotationException( \"Entity class '\" + annotatedClass.getName()\n\t\t\t\t\t+ \"' specifies an '@SQLRestriction' but it is a subclass in an entity inheritance hierarchy\"\n\t\t\t\t\t+ \" (only a root class may be specify a restriction)\" );\n\t\t}\n\t}\n\n\tprivate void ensureNoMutabilityPlan() {\n\t\tif ( annotatedClass.hasAnnotationUsage( Mutability.class, modelsContext() ) ) {\n\t\t\tthrow new MappingException( \"@Mutability is not allowed on entity\" );\n\t\t}\n\t}\n\n\tprivate boolean isMutable() {\n\t\treturn !annotatedClass.hasAnnotationUsage( Immutable.class, modelsContext() );","sourceCodeStart":1440,"sourceCodeEnd":1476,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java#L1440-L1476","documentation":"Error \"Entity class '${className}' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy (only a root class may declare its mutability)\" thrown in hibernate/hibernate-orm.","triggerScenarios":"An annotation restricted to the root of an inheritance hierarchy is placed on a subclass (or the hierarchy rules are otherwise violated).","commonSituations":"SINGLE_TABLE/JOINED hierarchies where @Table, @DiscriminatorColumn, @DiscriminatorFormula, @Cache, @Immutable, @Id or @Version are declared on the wrong class of the hierarchy.","solutions":["Remove @Immutable from the subclass; declare mutability only on the hierarchy root."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}