hibernate/hibernate-orm · error · SqlTreeCreationException

Could not locate TableGroup - " + navigablePath

Error message

Could not locate TableGroup - " + navigablePath

What it means

During SQL AST creation, every joined path is registered in a FromClauseAccess under its NavigablePath. getTableGroup(NavigablePath) is the strict accessor: when findTableGroup returns null, SqlTreeCreationException('Could not locate TableGroup - ' + path) is thrown, meaning the query references a path that was never registered as a table group in that from-clause scope.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/ast/spi/FromClauseAccess.java:52

	TableGroup findTableGroup(NavigablePath navigablePath);

	/**
	 * Find the TableGroup by the NavigablePath for the purpose of creating a
	 * new TableGroup if none can be found. Returns {@code null} if no TableGroup
	 * or parent table group is registered under that NavigablePath
	 */
	default TableGroup findTableGroupForGetOrCreate(NavigablePath navigablePath) {
		return findTableGroup( navigablePath );
	}

	/**
	 * Get a  TableGroup by the NavigablePath it is registered under.  If there is
	 * no registration, an exception is thrown.
	 */
	default TableGroup getTableGroup(NavigablePath navigablePath) throws SqlTreeCreationException {
		final TableGroup tableGroup = findTableGroup( navigablePath );
		if ( tableGroup == null ) {
			throw new SqlTreeCreationException( "Could not locate TableGroup - " + navigablePath );
		}
		return tableGroup;
	}

	/**
	 * Register a TableGroup under the given `navigablePath`.  Logs a message
	 * if this registration over-writes an existing one.
	 */
	void registerTableGroup(NavigablePath navigablePath, TableGroup tableGroup);

	/**
	 * Finds the TableGroup associated with the given `navigablePath`.  If one is not found,
	 * it is created via the given `creator`, registered under `navigablePath` and returned.
	 *
	 * @apiNote If the `creator` is called, there is no need for it to register the TableGroup
	 * it creates.  It will be registered by this method after.
	 *
	 * @see #findTableGroup

View on GitHub (pinned to fad1729dce)

Solutions

1. Check the HQL join aliases and association paths referenced in the failing query; make sure every path is introduced by a join in the same (or an outer) scope
2. Stop sharing/reusing Criteria or Query objects across threads; rebuild the query per execution
3. Simplify the query (split subqueries) to isolate the path that fails to resolve
4. Upgrade to the latest 6.x patch release - multiple table-group resolution fixes land there; if it persists, report with the query to HHH

Example fix

// before
select o from Order o where o.customer.name = 'x' and exists (select 1 from LineItem li where li.order = o2) // o2 undefined

// after
select o from Order o where o.customer.name = 'x' and exists (select 1 from LineItem li where li.order = o)

// Static sanity check: every alias referenced in HQL must be declared in a from/join of the same query (or outer scope)
Set<String> declared = extractDeclaredAliases(hql);
Set<String> referenced = extractReferencedAliases(hql);
if (!declared.containsAll(referenced)) { /* reject before execution */ }

try {
    query.list();
} catch (SqlTreeCreationException e) {
    if (String.valueOf(e.getMessage()).startsWith("Could not locate TableGroup")) {
        // log the NavigablePath from the message, fix alias scoping in the query
    } else throw e;
}

When it happens

Trigger: HQL/Criteria referencing a join alias or association path that is not present in the current from clause - e.g. reusing an alias from a different query, correlated subquery paths resolved against the wrong scope, join fetch alias reuse across duplicate joins, or SqmDeserialization/copy of criteria objects losing table group registrations.

Common situations: Dynamically built Criteria queries reused/mutated across threads; join alias typos or scope mistakes in complex HQL with subqueries; Hibernate 6.x bugs around correlated subqueries and implicit joins (many fixed in patches); copying/caching Criteria objects.

Related errors

• removeTableGroupJoin not supported by %s
• Summarization is not supported by DBMS!
• CollectionPersister used for [{}] does not support SQL AST
• Couldn't find table reference
• Function argument [%s] at specified position [%d] in call ar

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