{"record":{"id":"2cca1464ce9af263","repo":"hibernate/hibernate-orm","slug":"property-ref-propertypath-not-found-on-e","errorCode":null,"errorMessage":"property-ref [\" + propertyPath + \"] not found on entity [\" + getEntityName() + \"]","messagePattern":"property-ref \\[\" \\+ propertyPath \\+ \"\\] not found on entity \\[\" \\+ getEntityName\\(\\) \\+ \"\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java","lineNumber":546,"sourceCode":"\n\t/**\n\t * Given a property path, locate the appropriate referenceable property reference.\n\t * <p>\n\t * A referenceable property is a property  which can be a target of a foreign-key\n\t * mapping (e.g. {@code @ManyToOne}, {@code @OneToOne}).\n\t *\n\t * @param propertyPath The property path to resolve into a property reference.\n\t *\n\t * @return The property reference (never null).\n\t *\n\t * @throws MappingException If the property could not be found.\n\t */\n\tpublic Property getReferencedProperty(String propertyPath) throws MappingException {\n\t\ttry {\n\t\t\treturn getRecursiveProperty( propertyPath, getReferenceableProperties() );\n\t\t}\n\t\tcatch ( MappingException e ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"property-ref [\" + propertyPath + \"] not found on entity [\" + getEntityName() + \"]\", e\n\t\t\t);\n\t\t}\n\t}\n\n\tpublic Property getRecursiveProperty(String propertyPath) throws MappingException {\n\t\ttry {\n\t\t\treturn getRecursiveProperty( propertyPath, getPropertyClosure() );\n\t\t}\n\t\tcatch ( MappingException e ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"property [\" + propertyPath + \"] not found on entity [\" + getEntityName() + \"]\", e\n\t\t\t);\n\t\t}\n\t}\n\n\tprivate Property getRecursiveProperty(String propertyPath, List<Property> properties) throws MappingException {\n\t\tProperty property = null;","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java#L528-L564","documentation":"A mapping references a property of an entity by name (property-ref) and that property does not exist among the entity's referenceable properties. PersistentClass.getReferencedProperty() delegates to getRecursiveProperty over getReferenceableProperties() and rethrows with this message when the lookup fails. The name typically comes from a many-to-one/one-to-one property-ref attribute or a collection key property-ref.","triggerScenarios":"A many-to-one or one-to-one pointing at a target entity with property-ref naming a nonexistent property (typo, renamed field); property-ref configured against the wrong entity class; referencing a property declared on a subclass while the reference targets the root; a dotted path whose intermediate segment is not an embeddable.","commonSituations":"Renaming a Java field without updating XML property-ref attributes; switching the referenced entity class; porting old mappings whose target used to have the property.","solutions":["Fix the property-ref value to match an existing property name on the referenced entity","Verify the referenced class is the one that actually declares the property (check superclasses and subclasses)","For dotted paths, make sure every intermediate segment is an embeddable component","Prefer plain join-column mappings with a unique constraint instead of property-ref where possible"],"exampleFix":"// before\n<many-to-one name=\"user\" class=\"com.acme.User\" property-ref=\"userNamee\"/>\n\n// after\n<many-to-one name=\"user\" class=\"com.acme.User\" property-ref=\"userName\"/>","handlingStrategy":"validation","validationCode":"boolean resolvable = targetPc.getReferenceableProperties().stream()\n        .anyMatch(p -> p.getName().equals(propertyRefName));\nif (!resolvable) {\n    // fix the property-ref value before binding the association\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid property-ref: map the foreign key by column and add a unique constraint instead","When renaming fields, grep all mappings for property-ref usages of the old name","Keep a test that boots the full mapping so bad references fail at build time"],"tags":["hibernate","orm","property-ref","mapping","xml-mapping"],"backgroundTag":"unknown-property-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}