hibernate/hibernate-orm · error · MappingException

HBM return-join ResultSet mapping must be used in conjunctio

Error message

HBM return-join ResultSet mapping must be used in conjunction with root entity or collection return : " + registrationName

What it means

The implicit result set mapping builder treats joinDescriptors != null as 'this query has <return-join/> entries'. build() then requires at least one root return — foundEntityReturn or foundCollectionReturn — to attach the joins to. With joins present but neither root return found, this MappingException is thrown: a join fetch cannot be the only return of a native query.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/query/ImplicitHbmResultSetMappingDescriptorBuilder.java:152

		if ( fetchParentByAlias == null ) {
			fetchParentByAlias = new HashMap<>();
		}
		fetchParentByAlias.put( returnMapping.getAlias(), resultDescriptor );

		return this;
	}

	public HbmResultSetMappingDescriptor build(HbmLocalMetadataBuildingContext context) {
		if ( foundCollectionReturn && resultDescriptors.size() > 1 ) {
			throw new MappingException(
					"HBM return-collection ResultSet mapping cannot define entity or scalar returns : " + registrationName,
					context.getOrigin()
			);
		}

		if ( joinDescriptors != null ) {
			if ( ! foundEntityReturn && ! foundCollectionReturn ) {
				throw new MappingException(
						"HBM return-join ResultSet mapping must be used in conjunction with root entity or collection return : " + registrationName,
						context.getOrigin()
				);
			}
		}

		return new HbmResultSetMappingDescriptor(
				registrationName,
				resultDescriptors,
				joinDescriptors != null
						? joinDescriptors
						: Collections.emptyMap(),
				fetchParentByAlias != null
						? fetchParentByAlias
						: Collections.emptyMap()
		);
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Add a root <return alias="o" entity-name="..."/> (or <return-collection/>) whose alias matches the owner aliases used in the joins.
Make sure the root return is a direct child of <sql-query>, not nested inside another element where the builder would not count it.

Example fix

<!-- before: only a join, no root return -->
<sql-query name="q">
    <return-join alias="i" property="o.items"/>
</sql-query>

<!-- after -->
<sql-query name="q">
    <return alias="o" entity-name="com.acme.Order"/>
    <return-join alias="i" property="o.items"/>
</sql-query>

Defensive patterns

Strategy: validation

Validate before calling

boolean hasRootReturn = queryElement.element( "return" ) != null
        || queryElement.element( "return-collection" ) != null;
boolean hasJoins = !queryElement.elements( "return-join" ).isEmpty();
if ( hasJoins && !hasRootReturn ) {
    throw new IllegalStateException( "return-join requires a root return in query " + queryName );
}

Try / catch

catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "HBM return-join ResultSet mapping must be used in conjunction" ) ) {
        // e.getOrigin() names the file; add the missing <return> or <return-collection> root
    }
}

Prevention

Structure native query mappings as: one root return, then joins referencing its alias.
When trimming query returns, remove dependent joins together with the root return.

When it happens

Trigger: A <sql-query> containing only one or more <return-join property="o.items"/> elements with no <return/> or <return-collection/>; a root return accidentally deleted or commented out while the joins remained.

Common situations: Editing long native query mappings and dropping the root return; copy-pasting a join block into a new query skeleton that never got its root return; migrations where the root return element was renamed.

Related errors

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