hibernate/hibernate-orm · error · MappingException

<return-join/> did not specify alias [" + ownerTableAlias +

Error message

<return-join/> did not specify alias [" + ownerTableAlias + "." + propertyPath + "]

What it means

After splitting the <return-join/> property attribute into owner alias and property path, the JoinDescriptor constructor reads hbmJoinReturn.getAlias() and throws this MappingException when no alias attribute was supplied. The join's alias is what nested <return-property/> elements and downstream joins reference, so it is mandatory.

Source

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

				String registrationName,
				MetadataBuildingContext context) {
			this.joinDescriptorsAccess = joinDescriptorsAccess;
			this.fetchParentByAliasAccess = fetchParentByAliasAccess;
			final String fullPropertyPath = hbmJoinReturn.getProperty();
			final int firstDot = fullPropertyPath.indexOf( '.' );
			if ( firstDot < 1 ) {
				throw new MappingException(
						"Illegal <return-join/> property attribute: '" + fullPropertyPath + "'"
						+ " - should be in the form '{ownerAlias.joinedPropertyPath}'"
				);
			}

			ownerTableAlias = fullPropertyPath.substring( 0, firstDot );

			propertyPath = fullPropertyPath.substring( firstDot + 1 );
			tableAlias = hbmJoinReturn.getAlias();
			if ( tableAlias == null ) {
				throw new MappingException(
						"<return-join/> did not specify alias [" + ownerTableAlias + "." + propertyPath + "]"
				);
			}

			lockMode = hbmJoinReturn.getLockMode();
			propertyFetchDescriptors = extractPropertyFetchDescriptors(
					hbmJoinReturn.getReturnProperty(),
					this,
					registrationName,
					context
			);
		}

		@Override
		public String getFetchablePath() {
			return propertyPath;
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a unique alias: <return-join alias="i" property="o.items"/>.
2. Ensure the alias is distinct from all other aliases in the same result set mapping and is the one referenced by any nested return-property paths.

Example fix

<!-- before -->
<return-join property="o.items"/>

<!-- after -->
<return-join alias="i" property="o.items"/>

String alias = returnJoinElement.attributeValue( "alias" );
if ( alias == null || alias.isBlank() ) {
    throw new IllegalStateException( "return-join property=" + returnJoinElement.attributeValue( "property" ) + " needs an alias" );
}

catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "<return-join/> did not specify alias" ) ) {
        // message names ownerAlias.propertyPath; add the alias attribute to that join
    }
}

When it happens

Trigger: <return-join property="o.items"/> without an alias attribute; alias dropped when copying a join block; generated mappings that omit the attribute on joins.

Common situations: Hand-written or merged hbm.xml files; teams adding joins quickly during native-query tuning.

Related errors

• Illegal <return-join/> property attribute: '" + fullProperty
• Illegal <return-join/> property attribute: '" + fullProperty
• Cannot combine other returns with a collection return (" + r
• Property join specified twice for join-return '" + ownerTabl
• Entity <return/> mapping did not specify entity name

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