Practice Now
Hibernate
Error Resolution
Database
Java
ORM

Hibernate 6.1.5.Final unable to determine table reference

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
DatabasesJavaDebugging & Errors

Introduction

The "unable to determine table reference" error in Hibernate 6.1.x occurs when Hibernate cannot resolve which database table a column belongs to during query processing. This is a regression introduced in Hibernate 6's new query parser (SQM/SQL AST). Common causes include missing @Table annotations, ambiguous column references in JPQL queries with joins, incorrect @Column(table=...) attributes, and secondary table configurations. The fix depends on which mapping triggers the error.

The Error

java
1// Typical stack trace
2org.hibernate.sql.ast.SqlTreeCreationException:
3    Unable to determine table reference for column `status`
4    in the group `org.hibernate.sql.ast.tree.from.TableGroup`

This error surfaces during query compilation, not at startup. It means Hibernate built an SQL AST node for a column but could not find the table it belongs to.

Fix 1: Add or Fix @Table Annotation

java
1// WRONG — missing @Table, Hibernate may infer wrong table name
2@Entity
3public class OrderItem {
4    @Id
5    @GeneratedValue(strategy = GenerationType.IDENTITY)
6    private Long id;
7
8    private String status;  // Hibernate can't determine the table for this column
9}
10
11// CORRECT — explicit @Table annotation
12@Entity
13@Table(name = "order_items")
14public class OrderItem {
15    @Id
16    @GeneratedValue(strategy = GenerationType.IDENTITY)
17    private Long id;
18
19    @Column(name = "status")
20    private String status;
21}

Hibernate 6 is stricter about table resolution than Hibernate 5. Always provide an explicit @Table annotation, especially when the entity name differs from the desired table name.

Fix 2: Disambiguate JPQL Joins

java
1// WRONG — ambiguous column reference in a join query
2@Query("SELECT o FROM Order o JOIN o.items i WHERE status = :status")
3List<Order> findByStatus(@Param("status") String status);
4// Error: unable to determine table reference for column `status`
5// Both Order and OrderItem have a `status` field
6
7// CORRECT — qualify with the alias
8@Query("SELECT o FROM Order o JOIN o.items i WHERE o.status = :status")
9List<Order> findByStatus(@Param("status") String status);
10
11// CORRECT — reference the joined entity's field
12@Query("SELECT o FROM Order o JOIN o.items i WHERE i.status = :itemStatus")
13List<Order> findByItemStatus(@Param("itemStatus") String itemStatus);

Hibernate 6's SQM parser requires unambiguous column references in joins. Always prefix column names with the entity alias.

Fix 3: Fix @SecondaryTable Mapping

java
1@Entity
2@Table(name = "users")
3@SecondaryTable(name = "user_details",
4    pkJoinColumns = @PrimaryKeyJoinColumn(name = "user_id"))
5public class User {
6    @Id
7    @GeneratedValue(strategy = GenerationType.IDENTITY)
8    private Long id;
9
10    private String name;  // Maps to "users" table
11
12    // WRONG — Hibernate 6 can't determine which table this belongs to
13    // private String bio;
14
15    // CORRECT — specify the secondary table explicitly
16    @Column(table = "user_details")
17    private String bio;
18
19    @Column(table = "user_details")
20    private String avatarUrl;
21}

With @SecondaryTable, columns not in the primary table must have @Column(table = "secondary_table_name"). Hibernate 6 does not guess the table assignment.

Fix 4: Fix Inheritance Mapping

java
1// TABLE_PER_CLASS or JOINED inheritance can trigger this error
2@Entity
3@Inheritance(strategy = InheritanceType.JOINED)
4@Table(name = "payments")
5public abstract class Payment {
6    @Id
7    @GeneratedValue(strategy = GenerationType.IDENTITY)
8    private Long id;
9
10    private BigDecimal amount;
11}
12
13@Entity
14@Table(name = "credit_card_payments")
15public class CreditCardPayment extends Payment {
16    @Column(name = "card_number")
17    private String cardNumber;
18
19    // JPQL must use the correct alias
20    // SELECT p FROM Payment p WHERE p.amount > 100  — OK
21    // SELECT c FROM CreditCardPayment c WHERE c.amount > 100  — OK
22    // SELECT p FROM Payment p WHERE cardNumber IS NOT NULL  — ERROR
23}

In JOINED inheritance, each subclass has its own table. References to subclass fields in a query typed to the parent entity require explicit downcasting with TREAT.

Fix 5: Update Hibernate Version

xml
1<!-- pom.xml — update to a patched version -->
2<dependency>
3    <groupId>org.hibernate.orm</groupId>
4    <artifactId>hibernate-core</artifactId>
5    <version>6.2.7.Final</version>  <!-- or latest 6.x -->
6</dependency>
groovy
// build.gradle
implementation 'org.hibernate.orm:hibernate-core:6.2.7.Final'

Several "unable to determine table reference" cases were bugs in Hibernate 6.1.x that were fixed in 6.2+. If your mapping looks correct, upgrading to the latest 6.x patch often resolves the issue.

Fix 6: Native Query Workaround

java
1// If JPQL triggers the bug, use a native SQL query as a workaround
2@Query(value = "SELECT * FROM order_items WHERE status = :status", nativeQuery = true)
3List<OrderItem> findByStatusNative(@Param("status") String status);
4
5// Or use Criteria API
6CriteriaBuilder cb = entityManager.getCriteriaBuilder();
7CriteriaQuery<OrderItem> cq = cb.createQuery(OrderItem.class);
8Root<OrderItem> root = cq.from(OrderItem.class);
9cq.where(cb.equal(root.get("status"), status));
10List<OrderItem> results = entityManager.createQuery(cq).getResultList();

Native queries bypass the SQM parser entirely. The Criteria API may also avoid the bug because it builds the query tree differently.

Common Pitfalls

  • Upgrading from Hibernate 5 without testing queries: Hibernate 6 uses a completely rewritten query parser (SQM). Queries that worked in Hibernate 5 may fail in 6.x due to stricter column resolution.
  • Unqualified column names in joins: WHERE status = :val is ambiguous when multiple joined entities have a status field. Always use entity aliases: WHERE o.status = :val.
  • Missing @Column(table) for secondary tables: Hibernate 6 requires explicit table assignment for columns in @SecondaryTable. It does not infer the table based on column name.
  • Using @Formula without table context: @Formula annotations that reference columns without a table alias may confuse Hibernate 6's table resolution. Qualify column names in formulas.
  • Not checking the Hibernate issue tracker: Some "unable to determine table reference" errors are known bugs fixed in later patch versions. Check the Hibernate JIRA before investing time in workarounds.

Summary

  • The error occurs when Hibernate 6 cannot resolve which table a column belongs to
  • Add explicit @Table and @Column annotations to all entities and fields
  • Use entity aliases in JPQL joins to disambiguate column references
  • Specify @Column(table = "...") for all @SecondaryTable fields
  • Upgrade to the latest Hibernate 6.x — many cases were parser bugs fixed in 6.2+
  • Use native queries or Criteria API as workarounds when JPQL triggers the bug
Related reading
Course
Beginner
27 lessons
10 hours
System Design Fundamentals

Build a strong foundation in designing scalable, reliable distributed systems.

View the course
Track what you have practised

A free account saves your progress, solutions and study plan across every problem on Codemia.

System Design practice on Codemia

Work through 120+ system design problems with detailed solutions, from rate limiters to multi-region storage.

Practice system design
Codemia
© 2026 Codemia
Resources
Legal
Social
All Rights Reserved.