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}'

What it means

The JoinDescriptor constructor parses the <return-join/> property attribute by locating the first dot and splitting it into ownerTableAlias and propertyPath. When indexOf('.') returns a value below 1 (no dot, or a leading dot) the value cannot be split and this MappingException is thrown. It is the constructor-level twin of error 742, raised when the descriptor itself is instantiated.

Source

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

		private final String tableAlias;
		private final String propertyPath;
		private final LockMode lockMode;
		private final List<HbmFetchDescriptor> propertyFetchDescriptors;
		private final Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess;
		private final Supplier<Map<String, HbmFetchParent>> fetchParentByAliasAccess;

		public JoinDescriptor(
				JaxbHbmNativeQueryJoinReturnType hbmJoinReturn,
				Supplier<Map<String, Map<String, JoinDescriptor>>> joinDescriptorsAccess,
				Supplier<Map<String,HbmFetchParent>> fetchParentByAliasAccess,
				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(),

View on GitHub (pinned to fad1729dce)

Solutions

1. Rewrite the property attribute as '{ownerAlias}.{joinedPropertyPath}', e.g. property="o.items".
2. Confirm the alias before the dot is declared by a <return/> or <return-collection/> in the same mapping (otherwise you will next hit error 752).

Example fix

<!-- before -->
<return-join alias="li" property="lineItems"/>

<!-- after -->
<return-join alias="li" property="o.lineItems"/>

String prop = returnJoinElement.attributeValue( "property" );
if ( prop == null || prop.indexOf( '.' ) < 1 ) {
    throw new IllegalStateException( "return-join property must be 'ownerAlias.path': " + prop );
}

catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "Illegal <return-join/> property attribute" ) ) {
        // rewrite the property attribute as ownerAlias.propertyPath
    }
}

When it happens

Trigger: <return-join property="lineItems" .../> with no alias prefix; property=".items" starting with a dot; an empty alias variable substituted into the property string at generation time.

Common situations: Hand-edited hbm.xml files; template/merge artifacts where the owner alias token is missing; conversions from annotation-based mappings that omit alias prefixes.

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/c9b008c7dfe99697. Report an issue: GitHub.