{"record":{"id":"c9b008c7dfe99697","repo":"hibernate/hibernate-orm","slug":"illegal-return-join-property-attribute-fu-c9b008","errorCode":null,"errorMessage":"Illegal <return-join/> property attribute: '\" + fullPropertyPath + \"' - should be in the form '{ownerAlias.joinedPropertyPath}'","messagePattern":"Illegal <return-join/> property attribute: '\" \\+ fullPropertyPath \\+ \"' - should be in the form '(.+?)'","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java","lineNumber":722,"sourceCode":"\t\tprivate final String tableAlias;\n\t\tprivate final String propertyPath;\n\t\tprivate final LockMode lockMode;\n\t\tprivate final List<HbmFetchDescriptor> propertyFetchDescriptors;\n\t\tprivate final Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess;\n\t\tprivate final Supplier<Map<String, HbmFetchParent>> fetchParentByAliasAccess;\n\n\t\tpublic JoinDescriptor(\n\t\t\t\tJaxbHbmNativeQueryJoinReturnType hbmJoinReturn,\n\t\t\t\tSupplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess,\n\t\t\t\tSupplier<Map<String,HbmFetchParent>> fetchParentByAliasAccess,\n\t\t\t\tString registrationName,\n\t\t\t\tMetadataBuildingContext context) {\n\t\t\tthis.joinDescriptorsAccess = joinDescriptorsAccess;\n\t\t\tthis.fetchParentByAliasAccess = fetchParentByAliasAccess;\n\t\t\tfinal String fullPropertyPath = hbmJoinReturn.getProperty();\n\t\t\tfinal int firstDot = fullPropertyPath.indexOf( '.' );\n\t\t\tif ( firstDot < 1 ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Illegal <return-join/> property attribute: '\" + fullPropertyPath + \"'\"\n\t\t\t\t\t\t+ \" - should be in the form '{ownerAlias.joinedPropertyPath}'\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\townerTableAlias = fullPropertyPath.substring( 0, firstDot );\n\n\t\t\tpropertyPath = fullPropertyPath.substring( firstDot + 1 );\n\t\t\ttableAlias = hbmJoinReturn.getAlias();\n\t\t\tif ( tableAlias == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"<return-join/> did not specify alias [\" + ownerTableAlias + \".\" + propertyPath + \"]\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tlockMode = hbmJoinReturn.getLockMode();\n\t\t\tpropertyFetchDescriptors = extractPropertyFetchDescriptors(\n\t\t\t\t\thbmJoinReturn.getReturnProperty(),","sourceCodeStart":704,"sourceCodeEnd":740,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L704-L740","documentation":"The JoinDescriptor constructor parses the <return-join/> property attribute by locating the first dot and splitting it into ownerTableAlias and propertyPath. When indexOf('.') returns a value below 1 (no dot, or a leading dot) the value cannot be split and this MappingException is thrown. It is the constructor-level twin of error 742, raised when the descriptor itself is instantiated.","triggerScenarios":"<return-join property=\"lineItems\" .../> with no alias prefix; property=\".items\" starting with a dot; an empty alias variable substituted into the property string at generation time.","commonSituations":"Hand-edited hbm.xml files; template/merge artifacts where the owner alias token is missing; conversions from annotation-based mappings that omit alias prefixes.","solutions":["Rewrite the property attribute as '{ownerAlias}.{joinedPropertyPath}', e.g. property=\"o.items\".","Confirm the alias before the dot is declared by a <return/> or <return-collection/> in the same mapping (otherwise you will next hit error 752)."],"exampleFix":"<!-- before -->\n<return-join alias=\"li\" property=\"lineItems\"/>\n\n<!-- after -->\n<return-join alias=\"li\" property=\"o.lineItems\"/>","handlingStrategy":"validation","validationCode":"String prop = returnJoinElement.attributeValue( \"property\" );\nif ( prop == null || prop.indexOf( '.' ) < 1 ) {\n    throw new IllegalStateException( \"return-join property must be 'ownerAlias.path': \" + prop );\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( e.getMessage().startsWith( \"Illegal <return-join/> property attribute\" ) ) {\n        // rewrite the property attribute as ownerAlias.propertyPath\n    }\n}","preventionTips":["Require the alias-qualified form in every return-join; reject plain property names in review.","Boot all mappings in a unit test to catch malformed attributes early."],"tags":["hibernate","hbm-xml","native-query","return-join","boot"],"backgroundTag":"malformed-property-path","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}