hibernate/hibernate-orm · error · MappingException

Could not locate join-return owner by alias [" + ownerTableA

Error message

Could not locate join-return owner by alias [" + ownerTableAlias + "] for join path [" + propertyPath + "]

What it means

To resolve a <return-join/>, Hibernate looks up the owner side via fetchParentByAliasAccess.get().get(ownerTableAlias), the map of aliases registered by <return/> and <return-collection/> elements. When the alias prefix of the property attribute is not in that map, hbmFetchParent is null and this MappingException names the missing alias and the join path. The join references an owner that was never declared (or is spelled differently).

Source

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

						ownerTableAlias,
						tableAlias,
						keyColumnNames,
						lockMode,
						thisAsParentMemento,
						fetchDescriptorMap,
						(Fetchable) thisAsParentMemento.getFetchableContainer()
				);
			}

			return memento;
		}

		@Override
		public HbmFetchParentMemento resolveParentMemento(ResultSetMappingResolutionContext resolutionContext) {
			if ( thisAsParentMemento == null ) {
				final var hbmFetchParent = fetchParentByAliasAccess.get().get( ownerTableAlias );
				if ( hbmFetchParent == null ) {
					throw new MappingException(
							"Could not locate join-return owner by alias [" + ownerTableAlias + "] for join path [" + propertyPath + "]"
					);
				}

				final var ownerMemento = hbmFetchParent.resolveParentMemento( resolutionContext );

				final var parts = split( ".", propertyPath );
				NavigablePath navigablePath =
						ownerMemento.getFetchableContainer() instanceof PluralAttributeMapping
								? ownerMemento.getNavigablePath().append( CollectionPart.Nature.ELEMENT.getName() )
								: ownerMemento.getNavigablePath();
				navigablePath = navigablePath.append( parts[ 0 ] );
				FetchableContainer fetchable = (FetchableContainer)
						ownerMemento.getFetchableContainer().findSubPart( parts[ 0 ], null );

				for ( int i = 1; i < parts.length; i++ ) {
					navigablePath = navigablePath.append( parts[ i ] );
					fetchable = (FetchableContainer) fetchable.findSubPart( parts[ i ], null );

View on GitHub (pinned to fad1729dce)

Solutions

Make the alias before the dot exactly match an alias declared by a <return/> or <return-collection/> in the same mapping.
If no owner return exists, add one, e.g. <return alias="o" entity-name="com.acme.Order"/>.
Watch case sensitivity: 'Ord' does not match 'o' or 'O' beyond exact spelling.

Example fix

<!-- before: no return declares alias 'ord' -->
<sql-query name="q">
    <return alias="o" entity-name="com.acme.Order"/>
    <return-join alias="i" property="ord.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

// collect aliases declared by root returns, then check each join's owner prefix:
Set<String> declared = rootReturns.stream().map( r -> r.attributeValue( "alias" ) ).collect( toSet() );
for ( Element join : returnJoinElements ) {
    String owner = join.attributeValue( "property" ).split( "\\." )[0];
    if ( !declared.contains( owner ) ) {
        throw new IllegalStateException( "Join owner alias '" + owner + "' is not declared by any return/collection return" );
    }
}

Try / catch

catch ( MappingException e ) {
    if ( e.getMessage().startsWith( "Could not locate join-return owner by alias" ) ) {
        // message names the bad alias and join path; align it with the root return's alias attribute
    }
}

Prevention

Define the root return first, then copy its alias verbatim into join property prefixes.
After renaming an alias, search the whole query mapping for the old spelling.
Never leave joins whose root return was removed or commented out.

When it happens

Trigger: <return-join property="ord.items" .../> while the owner <return> declares alias="o"; owner return missing entirely (only joins in the query, see error 756); case mismatch between the alias in property and the alias attribute.

Common situations: Renaming an alias in the root return but not in join property attributes; deleting a root return while leaving its joins; copy-pasting joins between query mappings with different alias conventions.

Related errors

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