{"record":{"id":"3c8947ffcd7fef63","repo":"hibernate/hibernate-orm","slug":"hbm-return-collection-resultset-mapping-cannot-def","errorCode":null,"errorMessage":"HBM return-collection ResultSet mapping cannot define entity or scalar returns : \" + registrationName","messagePattern":"HBM return-collection ResultSet mapping cannot define entity or scalar returns : \" \\+ registrationName","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/ImplicitHbmResultSetMappingDescriptorBuilder.java","lineNumber":144,"sourceCode":"\t\t\t\treturnMapping,\n\t\t\t\t() -> joinDescriptors,\n\t\t\t\tregistrationName,\n\t\t\t\tmetadataBuildingContext\n\t\t);\n\n\t\tresultDescriptors.add( resultDescriptor );\n\n\t\tif ( fetchParentByAlias == null ) {\n\t\t\tfetchParentByAlias = new HashMap<>();\n\t\t}\n\t\tfetchParentByAlias.put( returnMapping.getAlias(), resultDescriptor );\n\n\t\treturn this;\n\t}\n\n\tpublic HbmResultSetMappingDescriptor build(HbmLocalMetadataBuildingContext context) {\n\t\tif ( foundCollectionReturn && resultDescriptors.size() > 1 ) {\n\t\t\tthrow new MappingException(\n\t\t\t\t\t\"HBM return-collection ResultSet mapping cannot define entity or scalar returns : \" + registrationName,\n\t\t\t\t\tcontext.getOrigin()\n\t\t\t);\n\t\t}\n\n\t\tif ( joinDescriptors != null ) {\n\t\t\tif ( ! foundEntityReturn && ! foundCollectionReturn ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"HBM return-join ResultSet mapping must be used in conjunction with root entity or collection return : \" + registrationName,\n\t\t\t\t\t\tcontext.getOrigin()\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn new HbmResultSetMappingDescriptor(\n\t\t\t\tregistrationName,\n\t\t\t\tresultDescriptors,\n\t\t\t\tjoinDescriptors != null","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/ImplicitHbmResultSetMappingDescriptorBuilder.java#L126-L162","documentation":"ImplicitHbmResultSetMappingDescriptorBuilder assembles a result set mapping from the returns nested directly inside a <sql-query/> element. Its build() method applies the same rule as error 741: when foundCollectionReturn is true and more than one result descriptor was collected, the mapping illegally mixes a <return-collection/> with entity or scalar returns and this MappingException (carrying the mapping origin) is thrown.","triggerScenarios":"A <sql-query> containing <return-collection/> plus a sibling <return/> or <return-column/>/<return-scalar/>; legacy query mappings where a scalar count column was appended next to a collection return.","commonSituations":"Older Hibernate versions tolerated looser structures; queries grown organically during maintenance; merging query definitions between files.","solutions":["Remove the entity/scalar returns so the collection return stands alone; use <return-join/> for associated data.","Or invert the design: keep the entity <return/> as root and join the collection with <return-join property=\"o.items\"/>.","Move unrelated scalar values into a separate named result set mapping or a separate query."],"exampleFix":"<!-- before -->\n<sql-query name=\"q\">\n    <return-scalar column=\"CNT\" type=\"long\"/>\n    <return-collection alias=\"i\" role=\"Order.items\"/>\n</sql-query>\n\n<!-- after -->\n<sql-query name=\"q\">\n    <return-collection alias=\"i\" role=\"Order.items\"/>\n</sql-query>","handlingStrategy":"validation","validationCode":"// pre-parse each <sql-query> and enforce the single-root rule:\nboolean collectionReturn = queryElement.element( \"return-collection\" ) != null;\nint rootReturns = queryElement.elements( \"return\" ).size()\n        + queryElement.elements( \"return-column\" ).size()\n        + queryElement.elements( \"return-scalar\" ).size();\nif ( collectionReturn && rootReturns > 0 ) {\n    throw new IllegalStateException( \"Collection return cannot be mixed with other returns in \" + queryName );\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( e.getMessage().startsWith( \"HBM return-collection ResultSet mapping cannot define\" ) ) {\n        // e.getOrigin() names the file/line; strip the extra root returns there\n    }\n}","preventionTips":["One root return per native query; joins for associations.","Boot every hbm.xml in a CI test — the MappingException origin pinpoints the file and line."],"tags":["hibernate","hbm-xml","native-query","result-set-mapping","boot"],"backgroundTag":"result-set-mapping-conflict","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}