{"record":{"id":"b17f9e77350ad058","repo":"hibernate/hibernate-orm","slug":"property-ref-s-referenced-an-unmapped-entity","errorCode":null,"errorMessage":"property-ref [%s] referenced an unmapped entity [%s]","messagePattern":"property-ref \\[(.+?)\\] referenced an unmapped entity \\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java","lineNumber":2838,"sourceCode":"\t\t\t\tOrigin propertyRefOrigin) {\n\t\t\tthis.referencedEntityName = referencedEntityName;\n\t\t\tthis.referencedPropertyName = referencedPropertyName;\n\t\t\tthis.isUnique = isUnique;\n\t\t\tthis.sourceElementSynopsis = sourceElementSynopsis;\n\t\t\tthis.propertyRefOrigin = propertyRefOrigin;\n\t\t}\n\n\t\tpublic void process(InFlightMetadataCollector metadataCollector) {\n\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}","sourceCodeStart":2820,"sourceCodeEnd":2856,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java#L2820-L2856","documentation":"property-ref (a legacy feature joining to a named non-PK property of the target, via <many-to-one property-ref=...>, <key property-ref=...>, or one-to-one property-ref) is resolved in a delayed second pass. If metadataCollector.getEntityBinding(referencedEntityName) returns null at that point, the referenced entity was never mapped and the second pass throws with the origin recorded where the property-ref was declared.","triggerScenarios":"property-ref='...' pointing at an entity whose name is misspelled or whose mapping file/class is not part of the SessionFactory's sources; using the class FQCN where the target declares an entity-name=.","commonSituations":"Legacy mappings relying on non-PK joins where the target class moved or was renamed; mapping files omitted during modularization; refactoring that changed entity names.","solutions":["Correct the referenced entity name to the actually mapped one (respect entity-name vs FQCN)","Add the missing target entity mapping to the metadata sources","Prefer joining by the target's primary key (drop property-ref) if the schema allows, since property-ref is a legacy construct"],"exampleFix":"// before\n<many-to-one name='user' class='com.acme.Usr' property-ref='ssn' column='user_ssn'/>\n\n// after\n<many-to-one name='user' class='com.acme.User' property-ref='ssn' column='user_ssn'/>","handlingStrategy":"validation","validationCode":"// gather all mapped entity names across sources, then verify each property-ref target exists\nMetadata metadata = metadataSources.buildMetadata(); // or scan all <class> names\nSet<String> entityNames = metadata.getEntityBindings().stream().map(PersistentClass::getEntityName).collect(Collectors.toSet());\nif (!entityNames.contains(referencedEntityNameFromPropertyRef)) {\n    throw new IllegalStateException(\"property-ref targets unmapped entity: \" + referencedEntityNameFromPropertyRef);\n}","typeGuard":null,"tryCatchPattern":"catch (MappingException e) at bootstrap; the message names the property-ref synopsis and the unmapped entity. Correct the name or add the missing mapping - this is deterministic, never retry.","preventionTips":["Centralize entity-name constants when using property-ref","Prefer primary-key joins over property-ref in new mappings","Rebuild all mappings as one unit so cross-file references stay consistent"],"tags":["hibernate","hbm-mapping","property-ref","foreign-key","legacy-mapping"],"backgroundTag":"unmapped-entity-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}