hibernate/hibernate-orm · error · MappingException

Illegal <return-join/> property attribute: '" + fullProperty

Error message

Illegal <return-join/> property attribute: '" + fullPropertyPath + "' -  - should be in the form '{ownerAlias.joinedPropertyPath}' (" + registrationName + ")

What it means

Thrown while collecting <return-join/> fetches for an HBM native query mapping when the property attribute cannot be split into an owner alias and a joined property path. The code takes fullPropertyPath.indexOf('.') and rejects the value when firstDot < 1, i.e. when there is no dot at all or the string starts with a dot. The value must literally be '{ownerAlias}.{joinedPropertyPath}'.

Source

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

			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(
					"Illegal <return-join/> property attribute: '" + fullPropertyPath + "' - "
					+ " - should be in the form '{ownerAlias.joinedPropertyPath}' (" + registrationName + ")"
			);
		}

		final String ownerTableAlias = fullPropertyPath.substring( 0, firstDot );
		final String propertyPath = fullPropertyPath.substring( firstDot + 1 );
		final String tableAlias = jaxbHbmJoin.getAlias();

		Map<String, JoinDescriptor> joinDescriptorsForAlias = joinDescriptors.get( ownerTableAlias );
		//noinspection Java8MapApi
		if ( joinDescriptorsForAlias == null ) {
			joinDescriptorsForAlias = new HashMap<>();
			joinDescriptors.put( ownerTableAlias, joinDescriptorsForAlias );
		}

		final JoinDescriptor existing = joinDescriptorsForAlias.get( propertyPath );
		if ( existing != null ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Set property to '{ownerAlias}.{joinedPropertyPath}', e.g. property="o.items" where 'o' is the alias of a <return> defined in the same mapping.
2. Make sure the alias used before the dot actually matches an alias declared by a <return/> or <return-collection/> in the same query mapping.
3. If the join hangs off a collection element, use the collection alias, e.g. property="i.element.owner".

Example fix

<!-- before: no owner alias before the dot -->
<return-join alias="i" property="items"/>

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

// validate every <return-join> property attribute before bootstrapping:
String prop = returnJoinElement.attributeValue( "property" );
int dot = prop == null ? -1 : prop.indexOf( '.' );
if ( prop == null || dot < 1 ) {
    throw new IllegalStateException( "return-join property must be 'ownerAlias.path': " + prop );
}

catch ( org.hibernate.MappingException e ) when it starts with "Illegal <return-join/> property attribute" {
    // rethrow with file/line context from your mapping source for fast diagnosis
}

When it happens

Trigger: <return-join property="items" .../> with no dot; <return-join property=".items" .../> starting with a dot; a property attribute built by string concatenation where the alias variable was empty.

Common situations: Hand-written or template-generated hbm.xml where the alias prefix is omitted; refactoring that drops the alias portion; confusion with JPA-style property names that do not carry an alias prefix.

Related errors

• Illegal <return-join/> property attribute: '" + fullProperty
• <return-join/> did not specify alias [" + ownerTableAlias +
• 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/f7d8a28d836a1621. Report an issue: GitHub.