hibernate/hibernate-orm · error · IllegalStateException

Unable to locate TableReference for '%s' : %s

Error message

Unable to locate TableReference for '%s' : %s

What it means

Error "Unable to locate TableReference for '%s' : %s" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/loader/ast/internal/AbstractNaturalIdLoader.java:184

			TableGroup rootTableGroup,
			Consumer<Predicate> predicateConsumer,
			BiConsumer<JdbcParameter, JdbcParameterBinding> jdbcParameterConsumer,
			LoaderSqlAstCreationState sqlAstCreationState,
			SharedSessionContractImplementor session);

	/**
	 * Helper to resolve ColumnReferences
	 */
	protected Expression resolveColumnReference(
			TableGroup rootTableGroup,
			SelectableMapping selectableMapping,
			SqlExpressionResolver sqlExpressionResolver) {
		final var tableReference = rootTableGroup.getTableReference(
				rootTableGroup.getNavigablePath(),
				selectableMapping.getContainingTableExpression()
		);
		if ( tableReference == null ) {
			throw new IllegalStateException(
					String.format(
							Locale.ROOT,
							"Unable to locate TableReference for '%s' : %s",
							selectableMapping.getContainingTableExpression(),
							rootTableGroup
					)
			);
		}
		return sqlExpressionResolver.resolveSqlExpression( tableReference, selectableMapping );
	}

	@Override
	public Object resolveNaturalIdToId(Object naturalIdValue, SharedSessionContractImplementor session) {
		if ( NATURAL_ID_LOGGER.isTraceEnabled() ) {
			NATURAL_ID_LOGGER.retrievingIdForNaturalId(
					entityDescriptor.getEntityName(),
					naturalIdValue instanceof Object[] array
							? Arrays.toString( array )

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the natural-id attribute name and mapping; ensure the referenced column/property exists in the entity mapping.

When it happens

Trigger: Thrown at hibernate-core/src/main/java/org/hibernate/loader/ast/internal/AbstractNaturalIdLoader.java:184 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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