hibernate/hibernate-orm · error · MappingException

Cannot combine other returns with a collection return (" + r

Error message

Cannot combine other returns with a collection return (" + registrationName + ")

What it means

Hibernate throws this MappingException while building an HBM native-query result set mapping when a <return-collection/> is combined with any other entity <return/> or <return-scalar/> return. The HbmResultSetMappingDescriptor constructor tracks foundCollectionReturn and rejects a descriptor list larger than one when a collection return is present, because a collection mapping must be the sole root return. Only <return-join/> entries may accompany it.

Source

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

				);
				localResultDescriptors.add( collectionResultDescriptor );
				fetchParentByAlias.put( collectionResultDescriptor.tableAlias, collectionResultDescriptor );
			}
			else if ( hbmValueMapping instanceof JaxbHbmNativeQueryJoinReturnType jaxbHbmJoinReturn ) {
				collectJoinFetch( jaxbHbmJoinReturn, joinDescriptors, fetchParentByAlias, registrationName, context );
			}
			else if ( hbmValueMapping instanceof JaxbHbmNativeQueryScalarReturnType hbmScalarReturn ) {
				localResultDescriptors.add( new ScalarDescriptor( hbmScalarReturn ) );
			}
			else {
				throw new IllegalArgumentException(
						"Unknown NativeQueryReturn type: " + hbmValueMapping.getClass().getName()
				);
			}
		}

		if ( foundCollectionReturn && localResultDescriptors.size() > 1 ) {
			throw new MappingException(
					"Cannot combine other returns with a collection return (" + registrationName + ")"
			);
		}

		this.resultDescriptors = localResultDescriptors;
	}

	public static void collectJoinFetch(
			JaxbHbmNativeQueryJoinReturnType jaxbHbmJoin,
			Map<String, Map<String, JoinDescriptor>> joinDescriptors,
			Map<String, HbmFetchParent> fetchParentByAlias,
			String registrationName,
			MetadataBuildingContext context) {
		// property path is in the form {ownerAlias}.{joinedPath}. Split it into the 2 parts.
		final String fullPropertyPath = jaxbHbmJoin.getProperty();
		final int firstDot = fullPropertyPath.indexOf( '.' );
		if ( firstDot < 1 ) {
			throw new MappingException(

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the entity <return/> and <return-scalar/> entries so the <return-collection/> is the only root return.
2. If you need the owning entity, keep only <return alias="o" class="Order"/> and reach the collection via <return-join alias="i" property="o.items"/> instead.
3. If scalar values are needed alongside the collection, return them via a different query or a second result set mapping.

Example fix

<!-- before -->
<sql-query name="ordersWithItems">
    <return alias="o" class="Order"/>
    <return-collection alias="i" role="Order.items"/>
</sql-query>

<!-- after: collection is the sole root return -->
<sql-query name="ordersWithItems">
    <return-collection alias="i" role="Order.items"/>
    <return-join alias="o" property="i.element.order"/>
</sql-query>

// before building the SessionFactory, inspect the parsed <sql-query>/<resultset> nodes:
// List<String> returnKinds = returns.stream().map(r -> r.elementName()).toList();
boolean hasCollectionReturn = returnKinds.contains( "return-collection" );
long roots = returnKinds.stream().filter( k -> k.equals( "return" ) || k.equals( "return-column" ) || k.equals( "return-scalar" ) ).count();
if ( hasCollectionReturn && roots > 0 ) {
    throw new IllegalStateException( "Collection return must be the sole root return in mapping " + name );
}

try {
    sessionFactory = metadata.buildSessionFactory();
}
catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "Cannot combine other returns with a collection return" ) ) {
        // fix the named mapping; message contains the registration name
    }
    throw e;
}

When it happens

Trigger: An hbm.xml <resultset> or <sql-query> element containing <return-collection/> together with a <return alias="..." class="..."/> or a <return-column/>/<return-scalar/> entry; migrating a legacy .hbm.xml file where extra returns were appended over time.

Common situations: Copy-pasting an entity return block into a collection-based native query mapping; upgrading old Hibernate 3/4 mappings to Hibernate 6 where the constraint is enforced at descriptor build time; attempting to fetch both the collection and its owner as separate root returns.

Related errors

• Entity <return/> mapping did not specify alias
• <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/9e617d3605fe2248. Report an issue: GitHub.