{"record":{"id":"500e30fd82330f99","repo":"hibernate/hibernate-orm","slug":"the-version-attribute-is-not-declared-by-this-type","errorCode":null,"errorMessage":"The version attribute is not declared by this type [{}]","messagePattern":"The version attribute is not declared by this type \\[(.+?)\\]","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/AbstractIdentifiableType.java","lineNumber":317,"sourceCode":"\t\t}\n\t\telse {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\t@Override\n\t@Nonnull\n\tpublic <Y> SingularPersistentAttribute<J, Y> getDeclaredVersion(@Nonnull Class<Y> javaType) {\n\t\tcheckDeclaredVersion();\n\t\tcheckType( versionAttribute, javaType );\n\t\t@SuppressWarnings(\"unchecked\") // safe, we just checked\n\t\tfinal var castVersion = (SingularPersistentAttribute<J, Y>) versionAttribute;\n\t\treturn castVersion;\n\t}\n\n\tprivate void checkDeclaredVersion() {\n\t\tif ( versionAttribute == null || supertypeDeclaresVersion() ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"The version attribute is not declared by this type [\" + getJavaType() + \"]\"\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate boolean supertypeDeclaresVersion() {\n\t\tfinal var superType = getSuperType();\n\t\treturn superType != null && superType.hasVersionAttribute();\n\t}\n\n//\t@Override\n//\tpublic void visitJdbcTypes(Consumer action, TypeConfiguration typeConfiguration) {\n//\t\tid.visitJdbcTypes( action, typeConfiguration );\n//\n//\t\tif ( versionAttribute != null ) {\n//\t\t\tversionAttribute.visitJdbcTypes( action, typeConfiguration );\n//\t\t}\n//","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/AbstractIdentifiableType.java#L299-L335","documentation":"getDeclaredVersion(Class) must return a version attribute declared on the type itself. checkDeclaredVersion() throws when versionAttribute == null OR when a supertype already declares the version (inherited versions are not 'declared'). This mirrors the declared-vs-inherited distinction of the JPA metamodel API.","triggerScenarios":"Calling getDeclaredVersion(...) on an entity whose @Version lives in a @MappedSuperclass (typical AbstractEntity base with @Version); calling it on a subtype of a versioned root entity in an inheritance hierarchy.","commonSituations":"Base-entity templates that centralize @Version in a shared superclass. Generic frameworks calling the declared variant to find 'own' fields.","solutions":["Use getVersion(Class) — it accepts inherited version attributes","Guard with hasVersionAttribute() plus knowledge that the version may be inherited; or move @Version onto the concrete class if declared semantics matter","Prefer findVersionAttribute() for nullable, hierarchy-aware lookup"],"exampleFix":"// before\nvar v = subtypeType.getDeclaredVersion(Long.class); // @Version on AbstractEntity -> throws\n\n// after\nvar v = subtypeType.getVersion(Long.class);","handlingStrategy":"validation","validationCode":"// Use hierarchy-aware getVersion(); declared-only if you must ensure 'own' declaration\nvar v = identifiableType.getVersion(javaType); // inherited ok\n// or: var v = identifiableType.findVersionAttribute(); // nullable","typeGuard":null,"tryCatchPattern":"try {\n    return type.getDeclaredVersion(cls);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"version attribute is not declared by this type\")) {\n        return type.getVersion(cls); // inherited version\n    }\n    throw e;\n}","preventionTips":["Remember @Version in a @MappedSuperclass makes getDeclaredVersion fail on every subtype","Default to getVersion(); use declared variant only for own-fields analysis","Keep a single optimistic-locking helper so policy is in one place"],"tags":["hibernate","jpa-metamodel","version-attribute","mapped-superclass","inheritance"],"backgroundTag":"jpa-metamodel-declared-vs-inherited","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}