hibernate/hibernate-orm · error · MappingException

HBM return-collection ResultSet mapping cannot define entity

Error message

HBM return-collection ResultSet mapping cannot define entity or scalar returns : " + registrationName

What it means

ImplicitHbmResultSetMappingDescriptorBuilder assembles a result set mapping from the returns nested directly inside a <sql-query/> element. Its build() method applies the same rule as error 741: when foundCollectionReturn is true and more than one result descriptor was collected, the mapping illegally mixes a <return-collection/> with entity or scalar returns and this MappingException (carrying the mapping origin) is thrown.

Source

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

				returnMapping,
				() -> joinDescriptors,
				registrationName,
				metadataBuildingContext
		);

		resultDescriptors.add( resultDescriptor );

		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

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the entity/scalar returns so the collection return stands alone; use <return-join/> for associated data.
2. Or invert the design: keep the entity <return/> as root and join the collection with <return-join property="o.items"/>.
3. Move unrelated scalar values into a separate named result set mapping or a separate query.

Example fix

<!-- before -->
<sql-query name="q">
    <return-scalar column="CNT" type="long"/>
    <return-collection alias="i" role="Order.items"/>
</sql-query>

<!-- after -->
<sql-query name="q">
    <return-collection alias="i" role="Order.items"/>
</sql-query>

// pre-parse each <sql-query> and enforce the single-root rule:
boolean collectionReturn = queryElement.element( "return-collection" ) != null;
int rootReturns = queryElement.elements( "return" ).size()
        + queryElement.elements( "return-column" ).size()
        + queryElement.elements( "return-scalar" ).size();
if ( collectionReturn && rootReturns > 0 ) {
    throw new IllegalStateException( "Collection return cannot be mixed with other returns in " + queryName );
}

catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "HBM return-collection ResultSet mapping cannot define" ) ) {
        // e.getOrigin() names the file/line; strip the extra root returns there
    }
}

When it happens

Trigger: A <sql-query> containing <return-collection/> plus a sibling <return/> or <return-column/>/<return-scalar/>; legacy query mappings where a scalar count column was appended next to a collection return.

Common situations: Older Hibernate versions tolerated looser structures; queries grown organically during maintenance; merging query definitions between files.

Related errors

• Cannot combine other returns with a collection return (" + r
• Entity <return/> mapping did not specify alias
• <return-collection/> did not specify alias - %s
• 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/3c8947ffcd7fef63. Report an issue: GitHub.