hibernate/hibernate-orm · error · SemanticException

Joining on basic value elements is not supported

Error message

Joining on basic value elements is not supported

What it means

Error "Joining on basic value elements is not supported" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/hql/internal/QualifiedJoinPathConsumer.java:221

						// and must not have a join condition.
						&& sqmJoin.getJoinPredicate() == null ) {
						// We explicitly allow reusing implicit joins of any type
						return sqmJoin;
					}
				}
			}
			else if ( fetch ) {
				final var compatibleFetchJoin = findCompatibleFetchJoin( lhs, subPathSource, joinType );
				if ( compatibleFetchJoin != null ) {
					if ( alias != null ) {
						throw new IllegalStateException( "Cannot fetch the same association twice with a different alias" );
					}
					return compatibleFetchJoin;
				}
			}
		}
		if ( !(subPathSource instanceof SqmJoinable) ) {
			throw new SemanticException( "Joining on basic value elements is not supported",
					((SemanticQueryBuilder<?>) creationState).getQuery() );
		}
		@SuppressWarnings("unchecked")
		final var joinSource = (SqmJoinable<U, ?>) subPathSource;
		return createJoin( lhs, joinType, alias, fetch, isTerminal, allowReuse, creationState, joinSource );
	}

	private static <U,V> SqmFrom<?, ?> createJoin(
			SqmFrom<?,U> lhs,
			SqmJoinType joinType,
			String alias,
			boolean fetch,
			boolean isTerminal,
			boolean allowReuse,
			SqmCreationState creationState,
			SqmJoinable<U,V> joinSource) {
		final var join = joinSource.createSqmJoin(
				lhs,

View on GitHub (pinned to fad1729dce)

Solutions

1. Join only entity associations or embeddables, not basic-valued collection elements.
2. Restructure the query to join the element's entity if applicable.

When it happens

Trigger: An API operation is invoked on an object that does not support it.

Common situations: Using query/procedure/proxy APIs beyond their supported feature set (e.g. scrolling, locking, unwrapping a procedure call).

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