hibernate/hibernate-orm · error · MappingException

Entity <return/> mapping did not specify alias

Error message

Entity <return/> mapping did not specify alias

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java:343

				String registrationName,
				MetadataBuildingContext context) {
			assert joinDescriptorsAccess != null;
			this.joinDescriptorsAccess = joinDescriptorsAccess;
			this.registrationName = registrationName;

			entityName =
					hbmEntityReturn.getEntityName() == null
							? context.getMetadataCollector().getImports().get( hbmEntityReturn.getClazz() )
							: hbmEntityReturn.getEntityName();
			if ( entityName == null ) {
				throw new MappingException(
						"Entity <return/> mapping did not specify entity name"
				);
			}

			tableAlias = hbmEntityReturn.getAlias();
			if ( tableAlias == null ) {
				throw new MappingException(
						"Entity <return/> mapping did not specify alias"
				);
			}

			BootQueryLogging.BOOT_QUERY_LOGGER.tracef(
					"Creating EntityResultDescriptor (%s : %s) for ResultSet mapping - %s",
					tableAlias,
					entityName,
					registrationName
			);

			discriminatorColumnAlias =
					hbmEntityReturn.getReturnDiscriminator() == null
							? null
							: hbmEntityReturn.getReturnDiscriminator().getColumn();
			lockMode = hbmEntityReturn.getLockMode();

			propertyFetchDescriptors = extractPropertyFetchDescriptors(

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a unique alias attribute: <return alias="o" clazz="com.acme.Order"/>.
2. Ensure the alias is unique within the result set mapping and matches what <return-join property="o..."/> references.

Example fix

<!-- before -->
<return clazz="com.acme.Order"/>

<!-- after -->
<return alias="o" clazz="com.acme.Order"/>

// while pre-parsing the mapping:
String alias = returnElement.attributeValue( "alias" );
if ( alias == null || alias.isBlank() ) {
    throw new IllegalStateException( "Entity <return> for " + returnElement.attributeValue( "clazz" ) + " needs an alias" );
}

catch ( MappingException e ) {
    if ( e.getMessage().contains( "did not specify alias" ) ) {
        // add alias="..." to the offending <return> element
    }
}

When it happens

Trigger: <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.

Common situations: Hand-written native query mappings; XSLT/code generation that omits the attribute; copying a <return-scalar/> style (no alias needed) into an entity return.

Related errors

• Cannot combine other returns with a collection return (" + r
• <return-collection/> did not specify alias - %s
• HBM return-collection ResultSet mapping cannot define entity
• Illegal <return-join/> property attribute: '" + fullProperty
• Entity <return/> mapping did not specify entity name

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/34083f8094964871. Report an issue: GitHub.