hibernate/hibernate-orm · error · UnsupportedMappingException

Entity mapping does not support primary TableReference join

Error message

Entity mapping does not support primary TableReference join creation [{className} : {entityName}]

What it means

Error "Entity mapping does not support primary TableReference join creation [{className} : {entityName}]" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/EntityMappingType.java:623

				creationState
		);
	}

	default TableReference createPrimaryTableReference(
			SqlAliasBase sqlAliasBase,
			SqlAstCreationState creationState) {
		throw new UnsupportedMappingException(
				"Entity mapping does not support primary TableReference creation [" +
						getClass().getName() + " : " + getEntityName() + "]"
		);
	}

	default TableReferenceJoin createTableReferenceJoin(
			String joinTableExpression,
			SqlAliasBase sqlAliasBase,
			TableReference lhs,
			SqlAstCreationState creationState) {
		throw new UnsupportedMappingException(
				"Entity mapping does not support primary TableReference join creation [" +
						getClass().getName() + " : " + getEntityName() + "]"
		);
	}

	@Override
	default JavaType<?> getMappedJavaType() {
		return getEntityPersister().getMappedJavaType();
	}

	@Override
	default int getNumberOfFetchables() {
		return getEntityPersister().getNumberOfFetchables();
	}

	@Override
	default Fetchable getFetchable(int position) {
		return getEntityPersister().getFetchable( position );

View on GitHub (pinned to fad1729dce)

Solutions

1. Avoid join fetches or query shapes that require a primary table join for this entity mapping, or report the limitation to Hibernate.

When it happens

Trigger: Thrown when SQL generation requests a primary table reference join from an entity mapping that does not support table group joins.

Common situations: See trigger scenarios.

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