{"record":{"id":"f7d8a28d836a1621","repo":"hibernate/hibernate-orm","slug":"illegal-return-join-property-attribute-fu","errorCode":null,"errorMessage":"Illegal <return-join/> property attribute: '\" + fullPropertyPath + \"' -  - should be in the form '{ownerAlias.joinedPropertyPath}' (\" + registrationName + \")","messagePattern":"Illegal <return-join/> property attribute: '\" \\+ fullPropertyPath \\+ \"' -  - should be in the form '(.+?)' \\(\" \\+ registrationName \\+ \"\\)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java","lineNumber":165,"sourceCode":"\t\t\tthrow new MappingException(\n\t\t\t\t\t\"Cannot combine other returns with a collection return (\" + registrationName + \")\"\n\t\t\t);\n\t\t}\n\n\t\tthis.resultDescriptors = localResultDescriptors;\n\t}\n\n\tpublic static void collectJoinFetch(\n\t\t\tJaxbHbmNativeQueryJoinReturnType jaxbHbmJoin,\n\t\t\tMap<String, Map<String, JoinDescriptor>> joinDescriptors,\n\t\t\tMap<String, HbmFetchParent> fetchParentByAlias,\n\t\t\tString registrationName,\n\t\t\tMetadataBuildingContext context) {\n\t\t// property path is in the form {ownerAlias}.{joinedPath}. Split it into the 2 parts.\n\t\tfinal String fullPropertyPath = jaxbHbmJoin.getProperty();\n\t\tfinal int firstDot = fullPropertyPath.indexOf( '.' );\n\t\tif ( firstDot < 1 ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"Illegal <return-join/> property attribute: '\" + fullPropertyPath + \"' - \"\n\t\t\t\t\t+ \" - should be in the form '{ownerAlias.joinedPropertyPath}' (\" + registrationName + \")\"\n\t\t\t);\n\t\t}\n\n\t\tfinal String ownerTableAlias = fullPropertyPath.substring( 0, firstDot );\n\t\tfinal String propertyPath = fullPropertyPath.substring( firstDot + 1 );\n\t\tfinal String tableAlias = jaxbHbmJoin.getAlias();\n\n\t\tMap<String, JoinDescriptor> joinDescriptorsForAlias = joinDescriptors.get( ownerTableAlias );\n\t\t//noinspection Java8MapApi\n\t\tif ( joinDescriptorsForAlias == null ) {\n\t\t\tjoinDescriptorsForAlias = new HashMap<>();\n\t\t\tjoinDescriptors.put( ownerTableAlias, joinDescriptorsForAlias );\n\t\t}\n\n\t\tfinal JoinDescriptor existing = joinDescriptorsForAlias.get( propertyPath );\n\t\tif ( existing != null ) {","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L147-L183","documentation":"Thrown while collecting <return-join/> fetches for an HBM native query mapping when the property attribute cannot be split into an owner alias and a joined property path. The code takes fullPropertyPath.indexOf('.') and rejects the value when firstDot < 1, i.e. when there is no dot at all or the string starts with a dot. The value must literally be '{ownerAlias}.{joinedPropertyPath}'.","triggerScenarios":"<return-join property=\"items\" .../> with no dot; <return-join property=\".items\" .../> starting with a dot; a property attribute built by string concatenation where the alias variable was empty.","commonSituations":"Hand-written or template-generated hbm.xml where the alias prefix is omitted; refactoring that drops the alias portion; confusion with JPA-style property names that do not carry an alias prefix.","solutions":["Set property to '{ownerAlias}.{joinedPropertyPath}', e.g. property=\"o.items\" where 'o' is the alias of a <return> defined in the same mapping.","Make sure the alias used before the dot actually matches an alias declared by a <return/> or <return-collection/> in the same query mapping.","If the join hangs off a collection element, use the collection alias, e.g. property=\"i.element.owner\"."],"exampleFix":"<!-- before: no owner alias before the dot -->\n<return-join alias=\"i\" property=\"items\"/>\n\n<!-- after -->\n<return-join alias=\"i\" property=\"o.items\"/>","handlingStrategy":"validation","validationCode":"// validate every <return-join> property attribute before bootstrapping:\nString prop = returnJoinElement.attributeValue( \"property\" );\nint dot = prop == null ? -1 : prop.indexOf( '.' );\nif ( prop == null || dot < 1 ) {\n    throw new IllegalStateException( \"return-join property must be 'ownerAlias.path': \" + prop );\n}","typeGuard":null,"tryCatchPattern":"catch ( org.hibernate.MappingException e ) when it starts with \"Illegal <return-join/> property attribute\" {\n    // rethrow with file/line context from your mapping source for fast diagnosis\n}","preventionTips":["Mandate the 'alias.property' form in code review of hbm.xml changes.","If generating mappings, assert the alias token is non-empty before concatenating.","Boot all mappings in a test so the failing file and element are identified before deployment."],"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"}