{"record":{"id":"34083f8094964871","repo":"hibernate/hibernate-orm","slug":"entity-return-mapping-did-not-specify-alias","errorCode":null,"errorMessage":"Entity <return/> mapping did not specify alias","messagePattern":"Entity <return/> mapping 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":343,"sourceCode":"\t\t\t\tString registrationName,\n\t\t\t\tMetadataBuildingContext context) {\n\t\t\tassert joinDescriptorsAccess != null;\n\t\t\tthis.joinDescriptorsAccess = joinDescriptorsAccess;\n\t\t\tthis.registrationName = registrationName;\n\n\t\t\tentityName =\n\t\t\t\t\thbmEntityReturn.getEntityName() == null\n\t\t\t\t\t\t\t? context.getMetadataCollector().getImports().get( hbmEntityReturn.getClazz() )\n\t\t\t\t\t\t\t: hbmEntityReturn.getEntityName();\n\t\t\tif ( entityName == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Entity <return/> mapping did not specify entity name\"\n\t\t\t\t);\n\t\t\t}\n\n\t\t\ttableAlias = hbmEntityReturn.getAlias();\n\t\t\tif ( tableAlias == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Entity <return/> mapping did not specify alias\"\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 EntityResultDescriptor (%s : %s) for ResultSet mapping - %s\",\n\t\t\t\t\ttableAlias,\n\t\t\t\t\tentityName,\n\t\t\t\t\tregistrationName\n\t\t\t);\n\n\t\t\tdiscriminatorColumnAlias =\n\t\t\t\t\thbmEntityReturn.getReturnDiscriminator() == null\n\t\t\t\t\t\t\t? null\n\t\t\t\t\t\t\t: hbmEntityReturn.getReturnDiscriminator().getColumn();\n\t\t\tlockMode = hbmEntityReturn.getLockMode();\n\n\t\t\tpropertyFetchDescriptors = extractPropertyFetchDescriptors(","sourceCodeStart":325,"sourceCodeEnd":361,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java#L325-L361","documentation":"An entity <return/> in an HBM native query mapping must carry an alias because every subsequent <return-join/> and <return-property/> references the owner by that alias. The EntityResultDescriptor constructor reads hbmEntityReturn.getAlias() and throws this MappingException immediately when it is null.","triggerScenarios":"<return clazz=\"com.acme.Order\"/> without an alias attribute; alias generated by tooling that skips the attribute; merging mapping files where the attribute got dropped.","commonSituations":"Hand-written native query mappings; XSLT/code generation that omits the attribute; copying a <return-scalar/> style (no alias needed) into an entity return.","solutions":["Add a unique alias attribute: <return alias=\"o\" clazz=\"com.acme.Order\"/>.","Ensure the alias is unique within the result set mapping and matches what <return-join property=\"o...\"/> references."],"exampleFix":"<!-- before -->\n<return clazz=\"com.acme.Order\"/>\n\n<!-- after -->\n<return alias=\"o\" clazz=\"com.acme.Order\"/>","handlingStrategy":"validation","validationCode":"// while pre-parsing the mapping:\nString alias = returnElement.attributeValue( \"alias\" );\nif ( alias == null || alias.isBlank() ) {\n    throw new IllegalStateException( \"Entity <return> for \" + returnElement.attributeValue( \"clazz\" ) + \" needs an alias\" );\n}","typeGuard":null,"tryCatchPattern":"catch ( MappingException e ) {\n    if ( e.getMessage().contains( \"did not specify alias\" ) ) {\n        // add alias=\"...\" to the offending <return> element\n    }\n}","preventionTips":["Always write entity/collection/join returns with an alias from the start; joins and return-properties depend on it.","Lint hbm.xml in CI: every <return>, <return-collection>, <return-join> must have a non-empty, unique alias."],"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"}