{"record":{"id":"b996ecc0ebea1855","repo":"hibernate/hibernate-orm","slug":"return-collection-did-not-specify-alias-s","errorCode":null,"errorMessage":"<return-collection/> did not specify alias - %s","messagePattern":"<return-collection/> did not specify alias - (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java","lineNumber":858,"sourceCode":"\t\tprivate final Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess;\n\t\tprivate final List<HbmFetchDescriptor> propertyFetchDescriptors;\n\n\t\tpublic CollectionResultDescriptor(\n\t\t\t\tJaxbHbmNativeQueryCollectionLoadReturnType hbmCollectionReturn,\n\t\t\t\tSupplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess,\n\t\t\t\tString registrationName,\n\t\t\t\tMetadataBuildingContext context) {\n\t\t\tfinal String role = hbmCollectionReturn.getRole();\n\t\t\tfinal int dotIndex = role.indexOf( '.' );\n\t\t\tfinal String entityName = role.substring( 0, dotIndex );\n\t\t\tfinal var metadataCollector = context.getMetadataCollector();\n\t\t\tfinal String fullEntityName = metadataCollector.getImports().get( entityName );\n\t\t\tcollectionPath = new NavigablePath(\n\t\t\t\t\tfullEntityName + \".\" + role.substring( dotIndex + 1 )\n\t\t\t);\n\t\t\ttableAlias = hbmCollectionReturn.getAlias();\n\t\t\tif ( tableAlias == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\t\"<return-collection/> did not specify alias - %s\",\n\t\t\t\t\t\t\t\tcollectionPath\n\t\t\t\t\t\t)\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tBootQueryLogging.BOOT_QUERY_LOGGER.tracef(\n\t\t\t\t\t\"Creating CollectionResultDescriptor (%s : %s)\",\n\t\t\t\t\ttableAlias,\n\t\t\t\t\tcollectionPath\n\t\t\t);\n\n//\t\t\tthis.lockMode = hbmCollectionReturn.getLockMode();\n\t\t\tthis.joinDescriptorsAccess = joinDescriptorsAccess;\n\n\t\t\tpropertyFetchDescriptors = extractPropertyFetchDescriptors(","sourceCodeStart":840,"sourceCodeEnd":876,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L840-L876","documentation":"The CollectionResultDescriptor constructor splits the role attribute into entity name and collection name, builds the collectionPath, then reads hbmCollectionReturn.getAlias(). A <return-collection/> without an alias attribute yields null and this MappingException is thrown, formatted with the resolved collection path. The alias is required because <return-join/> fetches hang off it.","triggerScenarios":"<return-collection role=\"Order.items\"/> with no alias attribute; tooling that emits the role but skips the alias.","commonSituations":"Hand-written legacy mappings; migrating old native queries where aliases were optional in different Hibernate versions.","solutions":["Add the alias attribute: <return-collection alias=\"i\" role=\"Order.items\"/>.","Ensure the alias is the one referenced by any <return-join property=\"i...\"/> in the same mapping."],"exampleFix":"<!-- before -->\n<return-collection role=\"Order.items\"/>\n\n<!-- after -->\n<return-collection alias=\"i\" role=\"Order.items\"/>","handlingStrategy":"validation","validationCode":"String alias = returnCollectionElement.attributeValue( \"alias\" );\nif ( alias == null || alias.isBlank() ) {\n    throw new IllegalStateException( \"return-collection role=\" + returnCollectionElement.attributeValue( \"role\" ) + \" needs an alias\" );\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( e.getMessage().startsWith( \"<return-collection/> did not specify alias\" ) ) {\n        // message contains the resolved collection path; add alias=\"...\" to that element\n    }\n}","preventionTips":["Every return element type (return, return-collection, return-join) requires an alias; treat it as mandatory in templates and reviews.","Automate an XML schema/lint pass over hbm.xml in the build."],"tags":["hibernate","hbm-xml","native-query","result-set-mapping","boot"],"backgroundTag":"missing-result-alias","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}