One common issue developers may face with Hibernate is the UnknownEntityException, particularly the message: Could not resolve root entity. This error, known as the Hibernate UnknownEntityException: Could not resolve root entity, typically arises when Hibernate cannot recognize the entity class being used. In this article, we’ll delve into the common causes of this exception and outline steps to resolve it.

1. Understanding the Exception

The UnknownEntityException usually occurs when Hibernate fails to locate the entity class referenced in your HQL (Hibernate Query Language) or JPQL (Jakarta Persistence Query Language) query. This often happens because the entity name in the query is incorrect.

2. Reproducing the UnknownEntityException

Before diving into the fixes, let’s explore an example that triggers this exception and then walk through the steps to resolve it. This will help us understand how the error occurs and how to resolve it.

Suppose we have the following Product class:

@Entity
public class Product {
 
 @Id
 private Long id;
 private String name;
 private Double price;

 public Long getId() {
 return id;
 }

 public void setId(Long id) {
 this.id = id;
 }

 public String getName() {
 return name;
 }

 public void setName(String name) {
 this.name = name;
 }

 public Double getPrice() {
 return price;
 }

 public void setPrice(Double price) {
 this.price = price;
 }
 
}

Code to Trigger the Exception

Let’s write a simple code snippet that triggers the UnknownEntityException: Could not resolve root entity Exception:

public class UnknownEntityExample {

 public static void main(String[] args) {
 EntityManagerFactory emf = Persistence.createEntityManagerFactory("example-unit");
 EntityManager em = emf.createEntityManager();

 em.getTransaction().begin();

 // This line will trigger the exception
 List<Product> products = em.createQuery("FROM PRODUCT", Product.class).getResultList(); 

 for (Product product : products) {
 System.out.println("Product ID: " + product.getId());
 System.out.println("Product Name: " + product.getName());
 System.out.println("Product Price: " + product.getPrice());
 System.out.println("---------------");
 }
 em.getTransaction().commit();

 em.close();
 emf.close();
 }
}

In the above example, the UnknownEntityException is triggered by the line:

List<Product> products = em.createQuery("FROM PRODUCT", Product.class).getResultList();

When you run the above code example, Hibernate attempts to execute the JPQL query to retrieve all Product entities from the database. However, because the query incorrectly references the entity name as PRODUCT instead of the correct Product, Hibernate cannot resolve the entity.

The error output typically looks like this:

This indicates that Hibernate couldn’t find an entity named PRODUCT, causing the exception to be thrown

3. Fixing the UnknownEntityException

As demonstrated in the above example, a common cause of UnknownEntityException is using an incorrect entity name in the query. Hibernate is case-sensitive regarding entity names, so if we reference an entity with a different case or name in our query, Hibernate won’t recognize it.

To resolve the exception, correct the entity name in the query. The entity class name must match exactly as it is defined in the class. In this example, the class is named Product, but the query is incorrectly using PRODUCT.

Replace the line:

List<Product> products = em.createQuery("FROM PRODUCT", Product.class).getResultList();

with:

List<Product> products = em.createQuery("FROM Product", Product.class).getResultList();

4. Conclusion

In this article, we’ve explored the common cause of the UnknownEntityException in Hibernate, specifically focusing on how an incorrect entity name in a JPQL query can trigger this error. We walked through an example where this exception occurs due to a mismatch between the entity name in the query and the actual class name. By ensuring the entity names in our queries are accurate, we can avoid this exception and ensure the smooth execution of our Hibernate-based applications.

5. Download the Source Code

This article focused on the Hibernate UnknownEntityException: Could not resolve root entity.