{"record":{"id":"af852ad82e902057","repo":"hibernate/hibernate-orm","slug":"class-propertyholder-getentityname-is","errorCode":null,"errorMessage":"Class '\" + propertyHolder.getEntityName() + \"' is annotated '@IdClass' and may not have a property annotated '@Version'","messagePattern":"Class '\" \\+ propertyHolder\\.getEntityName\\(\\) \\+ \"' is annotated '@IdClass' and may not have a property annotated '@Version'","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyBinder.java","lineNumber":1094,"sourceCode":"\t\t\t\tgetMappedSuperclassOrNull( declaringClass,\n\t\t\t\t\t\tinheritanceStatePerClass, buildingContext );\n\t\tif ( mappedSuperclass != null ) {\n\t\t\t// Don't overwrite an existing version property\n\t\t\tif ( mappedSuperclass.getDeclaredVersion() == null ) {\n\t\t\t\tmappedSuperclass.setDeclaredVersion( property );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\t//we know the property is on the actual entity\n\t\t\trootClass.setDeclaredVersion( property );\n\t\t}\n\n\t\trootClass.setOptimisticLockStyle( OptimisticLockStyle.VERSION );\n\t}\n\n\tprivate static void checkVersionProperty(PropertyHolder propertyHolder, boolean isIdentifierMapper) {\n\t\tif ( isIdentifierMapper ) {\n\t\t\tthrow new AnnotationException( \"Class '\" + propertyHolder.getEntityName()\n\t\t\t\t\t+ \"' is annotated '@IdClass' and may not have a property annotated '@Version'\"\n\t\t\t);\n\t\t}\n\t\tif ( !( propertyHolder.getPersistentClass() instanceof RootClass ) ) {\n\t\t\tthrow new AnnotationException( \"Entity '\" + propertyHolder.getEntityName()\n\t\t\t\t\t+ \"' is a subclass in an entity class hierarchy and may not have a property annotated '@Version'\" );\n\t\t}\n\t\tif ( !propertyHolder.isEntity() ) {\n\t\t\tthrow new AnnotationException( \"Embedded class '\" + propertyHolder.getEntityName()\n\t\t\t\t\t+ \"' may not have a property annotated '@Version'\" );\n\t\t}\n\t}\n\n\tprivate AnnotatedColumns bindBasicOrComposite(\n\t\t\tPropertyHolder propertyHolder,\n\t\t\tNullability nullability,\n\t\t\tPropertyData inferredData,\n\t\t\tEntityBinder entityBinder,","sourceCodeStart":1076,"sourceCodeEnd":1112,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/PropertyBinder.java#L1076-L1112","documentation":"A class mapped with @IdClass must not declare a @Version property: version/optimistic-lock state belongs to the entity itself, not to the composite-id mirror class. PropertyBinder detects the situation while binding the id-class property mapper (isIdentifierMapper) and throws AnnotationException at bootstrap.","triggerScenarios":"An @IdClass class (e.g. OrderLineId) containing a field annotated @Version; usually the id-class was created by copying all fields from the entity, version included.","commonSituations":"Hand-written id classes cloned from the entity; introducing optimistic locking into a composite-key entity by adding @Version 'everywhere'; code generators that mirror all entity fields into the id class.","solutions":["Delete the @Version property from the @IdClass; keep only the id fields.","Put @Version on the owning @Entity class instead (its root, per the related subclass check)."],"exampleFix":"// before\npublic class OrderLineId implements Serializable {\n    private Long order;\n    private Long line;\n    @Version                 // rejected inside an @IdClass\n    private int version;\n}\n\n// after\npublic class OrderLineId implements Serializable {\n    private Long order;\n    private Long line;\n}\n// and on the entity:\n@Entity\n@IdClass(OrderLineId.class)\npublic class OrderLine {\n    @Id private Long order;\n    @Id private Long line;\n    @Version private int version;\n}","handlingStrategy":"validation","validationCode":"// Id classes must mirror only id fields — no @Version\nfor (Class<?> entity : annotatedClasses) {\n    IdClass idClass = entity.getAnnotation(IdClass.class);\n    if (idClass == null) continue;\n    for (Field f : idClass.value().getDeclaredFields()) {\n        if (f.isAnnotationPresent(Version.class)) {\n            throw new IllegalStateException(\"@IdClass \" + idClass.value().getName() + \" contains @Version field \" + f.getName());\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    SessionFactory sf = cfg.buildSessionFactory();\n} catch (AnnotationException e) {\n    throw new IllegalStateException(\"@IdClass contains forbidden property: \" + e.getMessage(), e);\n}","preventionTips":["Keep id classes minimal: only the id fields, Serializable, equals/hashCode","Declare @Version on the entity, never on the id class"],"tags":["hibernate","jpa","idclass","version","optimistic-lock","bootstrap"],"backgroundTag":"version-property-misplaced","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}