{"record":{"id":"072d68ebefe4565f","repo":"hibernate/hibernate-orm","slug":"could-not-locate-tablegroup-navigablepath","errorCode":null,"errorMessage":"Could not locate TableGroup - \" + navigablePath","messagePattern":"Could not locate TableGroup - \" \\+ navigablePath","errorType":"exception","errorClass":"SqlTreeCreationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/sql/ast/spi/FromClauseAccess.java","lineNumber":52,"sourceCode":"\tTableGroup findTableGroup(NavigablePath navigablePath);\n\n\t/**\n\t * Find the TableGroup by the NavigablePath for the purpose of creating a\n\t * new TableGroup if none can be found. Returns {@code null} if no TableGroup\n\t * or parent table group is registered under that NavigablePath\n\t */\n\tdefault TableGroup findTableGroupForGetOrCreate(NavigablePath navigablePath) {\n\t\treturn findTableGroup( navigablePath );\n\t}\n\n\t/**\n\t * Get a  TableGroup by the NavigablePath it is registered under.  If there is\n\t * no registration, an exception is thrown.\n\t */\n\tdefault TableGroup getTableGroup(NavigablePath navigablePath) throws SqlTreeCreationException {\n\t\tfinal TableGroup tableGroup = findTableGroup( navigablePath );\n\t\tif ( tableGroup == null ) {\n\t\t\tthrow new SqlTreeCreationException( \"Could not locate TableGroup - \" + navigablePath );\n\t\t}\n\t\treturn tableGroup;\n\t}\n\n\t/**\n\t * Register a TableGroup under the given `navigablePath`.  Logs a message\n\t * if this registration over-writes an existing one.\n\t */\n\tvoid registerTableGroup(NavigablePath navigablePath, TableGroup tableGroup);\n\n\t/**\n\t * Finds the TableGroup associated with the given `navigablePath`.  If one is not found,\n\t * it is created via the given `creator`, registered under `navigablePath` and returned.\n\t *\n\t * @apiNote If the `creator` is called, there is no need for it to register the TableGroup\n\t * it creates.  It will be registered by this method after.\n\t *\n\t * @see #findTableGroup","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/sql/ast/spi/FromClauseAccess.java#L34-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Stop sharing/reusing Criteria or Query objects across threads; rebuild the query per execution","Simplify the query (split subqueries) to isolate the path that fails to resolve","Upgrade to the latest 6.x patch release - multiple table-group resolution fixes land there; if it persists, report with the query to HHH"],"exampleFix":"// before\nselect o from Order o where o.customer.name = 'x' and exists (select 1 from LineItem li where li.order = o2) // o2 undefined\n\n// after\nselect o from Order o where o.customer.name = 'x' and exists (select 1 from LineItem li where li.order = o)","handlingStrategy":"try-catch","validationCode":"// Static sanity check: every alias referenced in HQL must be declared in a from/join of the same query (or outer scope)\nSet<String> declared = extractDeclaredAliases(hql);\nSet<String> referenced = extractReferencedAliases(hql);\nif (!declared.containsAll(referenced)) { /* reject before execution */ }","typeGuard":null,"tryCatchPattern":"try {\n    query.list();\n} catch (SqlTreeCreationException e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"Could not locate TableGroup\")) {\n        // log the NavigablePath from the message, fix alias scoping in the query\n    } else throw e;\n}","preventionTips":["Introduce every join alias in the same query scope before referencing it","Never share Criteria/Query objects across threads or sessions; build them per request","Upgrade to the latest 6.x patch - several table-group resolution bugs were fixed"],"tags":["hibernate","sql-ast","table-group","navigable-path","query-resolution"],"backgroundTag":"table-group-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}