{"record":{"id":"c8c180a0c78700e7","repo":"hibernate/hibernate-orm","slug":"property-ref-s-referenced-an-unknown-entity-pro","errorCode":null,"errorMessage":"property-ref [%s] referenced an unknown entity property [%s.%s]","messagePattern":"property-ref \\[(.+?)\\] referenced an unknown entity property \\[(.+?)\\.(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java","lineNumber":2847,"sourceCode":"\t\t\tBOOT_LOGGER.tracef(\n\t\t\t\t\t\"Performing delayed property-ref handling [%s, %s, %s]\",\n\t\t\t\t\treferencedEntityName,\n\t\t\t\t\treferencedPropertyName,\n\t\t\t\t\tsourceElementSynopsis\n\t\t\t);\n\n\t\t\tfinal var entityBinding = metadataCollector.getEntityBinding( referencedEntityName );\n\t\t\tif ( entityBinding == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"property-ref [%s] referenced an unmapped entity [%s]\"\n\t\t\t\t\t\t\t\t.formatted( sourceElementSynopsis, referencedEntityName ),\n\t\t\t\t\t\tpropertyRefOrigin\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tfinal var propertyBinding = entityBinding.getReferencedProperty( referencedPropertyName );\n\t\t\tif ( propertyBinding == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"property-ref [%s] referenced an unknown entity property [%s.%s]\"\n\t\t\t\t\t\t\t\t.formatted( sourceElementSynopsis, referencedEntityName, referencedPropertyName ),\n\t\t\t\t\t\tpropertyRefOrigin\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tif ( isUnique ) {\n\t\t\t\t( (SimpleValue) propertyBinding.getValue() ).setAlternateUniqueKey( true );\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate abstract class AbstractPluralAttributeSecondPass implements SecondPass {\n\t\tprivate final MappingDocument mappingDocument;\n\t\tprivate final PluralAttributeSource pluralAttributeSource;\n\t\tprivate final Collection collectionBinding;\n\n\t\tprotected AbstractPluralAttributeSecondPass(","sourceCodeStart":2829,"sourceCodeEnd":2865,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java#L2829-L2865","documentation":"The companion of the unmapped-entity check: the entity referenced by property-ref IS bound, but entityBinding.getReferencedProperty(referencedPropertyName) returned null - the property named by property-ref does not exist on the target entity as a referable (persistent) property. Thrown from the same delayed second pass with the property-ref origin.","triggerScenarios":"property-ref='userName' where the target entity has no such persistent property; the target field was renamed while the referencing mapping kept the old name; referencing a transient/computed field or a path that is not exposed as a referable property.","commonSituations":"Field renames on the target entity without sweeping property-ref usages; unique-key columns later removed from the mapping; case mismatches in property names.","solutions":["Align property-ref with an existing, ideally unique, persistent property of the target entity","If the target property was renamed, update every property-ref that names it","Make sure the referenced property is actually mapped (<property> and not transient/calculated)"],"exampleFix":"// before\n<many-to-one name='user' class='User' property-ref='userName' column='login'/>\n\n// after\n<many-to-one name='user' class='User' property-ref='loginName' column='login'/>","handlingStrategy":"validation","validationCode":"// after all classes are mapped, verify each property-ref names a real persistent property\nPersistentClass pc = metadata.getEntityBinding(referencedEntityName);\nif (pc.getReferencedProperty(referencedPropertyName) == null) {\n    throw new IllegalStateException(\"property-ref names unknown property \" + referencedEntityName + \".\" + referencedPropertyName);\n}","typeGuard":null,"tryCatchPattern":"catch (MappingException e) at bootstrap; the message gives entity and property. Rename the property-ref value to a mapped (ideally unique) property of that entity.","preventionTips":["When renaming a persistent property, grep mappings for property-ref usages","Mark property-ref targets unique in their own mapping for sane SQL","Cover legacy property-ref mappings with SessionFactory smoke tests in CI"],"tags":["hibernate","hbm-mapping","property-ref","unknown-property","foreign-key"],"backgroundTag":"unknown-property-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}