Hibernate 6.1.5.Final unable to determine table reference

Hibernate

Error Resolution

Database

Java

ORM

Hibernate 6.1.5.Final unable to determine table reference

Master System Design with Codemia

Enhance your system design skills with over 120 practice problems, detailed solutions, and hands-on exercises.

Start Practicing Learn More

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