What causes "Entity join treats can not be aliased" in hibernate/hibernate-orm?

Drop the alias: call the no-alias overload treatAs(SubType.class) — supported for entity joins; the treated node shares the original join alias.

hibernate/hibernate-orm · error · UnsupportedOperationException

Entity join treats can not be aliased

Error message

Entity join treats can not be aliased

What it means

SqmEntityJoin models a join to an unrelated entity type: HQL `join Employee e on ...`, criteria `JpaFrom.join(Class)`/`join(EntityDomainType)`. Treat on an entity join IS supported, but only without its own alias — the working overloads create an SqmTreatedEntityJoin that reuses the original join's identification variable. This treatAs(Class<S> treatJavaType, String alias) overload throws UnsupportedOperationException because the SQM model cannot attach a second alias to a treated entity join.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sqm/tree/spi/from/SqmEntityJoin.java:206

		return treatAs( nodeBuilder().getDomainModel().entity( treatAsType ) );
	}

	@Nonnull
	@Override
	public <S extends R> SqmTreatedEntityJoin<L,R,S> treatAs(@Nonnull EntityDomainType<S> treatAsType) {
		final var treat = (SqmTreatedEntityJoin<L, R, S>) findTreat( treatAsType, null );
		if ( treat == null ) {
			return addTreat( new SqmTreatedEntityJoin<>( this, (SqmEntityDomainType<S>) treatAsType, null ) );
		}
		else {
			return treat;
		}
	}

	@Override
	@Nonnull
	public <S extends R> SqmTreatedEntityJoin<L,R,S> treatAs(@Nonnull Class<S> treatJavaType, @Nullable String alias) {
		throw new UnsupportedOperationException( "Entity join treats can not be aliased" );
	}

	@Override
	@Nonnull
	public <S extends R> SqmTreatedEntityJoin<L,R,S> treatAs(@Nonnull EntityDomainType<S> treatTarget, @Nullable String alias) {
		throw new UnsupportedOperationException( "Entity join treats can not be aliased" );
	}

	@Override
	@Nonnull
	public <S extends R> SqmTreatedEntityJoin<L,R,S> treatAs(@Nonnull Class<S> treatJavaType, @Nullable String alias, boolean fetched) {
		throw new UnsupportedOperationException( "Entity join treats can not be aliased" );
	}

	@Override
	@Nonnull
	public <S extends R> SqmTreatedEntityJoin<L,R,S> treatAs(@Nonnull EntityDomainType<S> treatTarget, @Nullable String alias, boolean fetched) {
		throw new UnsupportedOperationException( "Entity join treats can not be aliased" );

View on GitHub (pinned to fad1729dce)

Solutions

Drop the alias: call the no-alias overload treatAs(SubType.class) — supported for entity joins; the treated node shares the original join alias.
In HQL, use treat as a path expression (`treat(e as Manager).salary`) instead of binding the treat to a new alias.
If a distinct subtype identification variable is truly required, join the subtype entity directly (`join Manager m on ...`) instead of treating.

Example fix

// before - UnsupportedOperationException: Entity join treats can not be aliased
JpaEntityJoin<Order, Person> ej = order.join( Person.class );
ej.treatAs( Manager.class, "m" );

// after - no-alias overload; treated join reuses alias of ej
JpaTreatedJoin<Order, Person, Manager> treated = ej.treatAs( Manager.class );
query.where( cb.gt( treated.get( "salary" ), 1000 ) );

Defensive patterns

Strategy: type-guard

Validate before calling

import org.hibernate.query.sqm.tree.spi.from.*;

if ( join instanceof SqmEntityJoin<?, ?> ) {
    // entity joins support treat ONLY without an alias
    treated = join.treatAs( Sub.class );
} else {
    treated = join.treatAs( Sub.class, alias );
}

Type guard

static boolean treatSupportsAlias(Join<?, ?> join) {
    return !( join instanceof SqmEntityJoin<?, ?> );
}

Try / catch

try {
    return join.treatAs( type, alias );
} catch ( UnsupportedOperationException e ) {
    if ( "Entity join treats can not be aliased".equals( e.getMessage() ) ) {
        return join.treatAs( type ); // recover once via the no-alias overload
    }
    throw e;
}

Prevention

For entity joins, always call the no-alias treatAs(Class) overload; the treat shares the original join alias.
In HQL, write treat as a path expression (treat(e as Manager).salary) instead of binding a new alias.
Need a distinct subtype variable? Join the subtype entity directly rather than treating.
Centralize treats in one helper that knows the entity-join special case.

When it happens

Trigger: Calling treatAs(SubType.class, "t") on a JpaEntityJoin obtained from root.join(Other.class); HQL that assigns the treat a new alias over an entity join (`join treat(e as Manager) m`); SQM rewriters replaying aliased treats on SqmEntityJoin nodes.

Common situations: Copy-pasting treat syntax from attribute joins (where `join treat(o.x as Sub) alias` is legal) onto entity joins; query-DSL helpers that always pass an alias to treatAs; switching a query from an association join to an unrelated entity join while keeping the treated alias.

Related errors

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