hibernate/hibernate-orm · error · UnknownTableReferenceException

Unable to determine TableReference (`%s`) for `%s`

Error message

Unable to determine TableReference (`%s`) for `%s`

What it means

Error "Unable to determine TableReference (`%s`) for `%s`" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/internal/SimpleForeignKeyDescriptor.java:365

	private <T> DomainResult<T> createDomainResult(
			NavigablePath navigablePath,
			TableGroup tableGroup,
			BasicValuedModelPart selectableMapping,
			FetchParent fetchParent,
			DomainResultCreationState creationState) {
		final var sqlAstCreationState = creationState.getSqlAstCreationState();
		final var sqlExpressionResolver = sqlAstCreationState.getSqlExpressionResolver();
		final TableReference tableReference;
		try {
			tableReference = tableGroup.resolveTableReference(
					navigablePath,
					selectableMapping,
					selectableMapping.getContainingTableExpression()
			);
		}
		catch (IllegalStateException tableNotFoundException) {
			throw new UnknownTableReferenceException(
					selectableMapping.getContainingTableExpression(),
					String.format(
							Locale.ROOT,
							"Unable to determine TableReference (`%s`) for `%s`",
							selectableMapping.getContainingTableExpression(),
							getNavigableRole().getFullPath()
					)
			);
		}

		final var javaType = selectableMapping.getJdbcMapping().getJdbcJavaType();
		final var sqlSelection = sqlExpressionResolver.resolveSqlSelection(
				sqlExpressionResolver.resolveSqlExpression( tableReference, selectableMapping ),
				javaType,
				fetchParent,
				sqlAstCreationState.getCreationContext().getTypeConfiguration()
		);

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the join column/table names in the association mapping refer to tables that are part of the current query's table group.

When it happens

Trigger: Thrown when a simple foreign key descriptor cannot determine the referenced table for its key column during SQL rendering.

Common situations: See trigger scenarios.

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