How to Fix Hibernate UnknownEntityException: Could not resolve root entity

1. Overview

In this short tutorial, we’ll elucidate how to solve the Hibernate UnknownEntityException: “Could not resolve root entity”.

First, we’ll explain the root cause leading to the exception. Then, we’ll illustrate how to reproduce and fix it in practice.

2. Understanding the Exception

Before jumping to the solution, let’s take a moment to understand the exception and its stack trace.

Typically, Hibernate throws “UnknownEntityException: Could not resolve root entity” to signal a failure to resolve a known mapped entity name in HQL or JPQL queries.

In short, Hibernate relies on JPA entities to do all the heavy lifting of object-relational mapping. As a result, it expects the entity name specified in queries to match a class name annotated by the @Entity annotation.

So, one of the most common causes of the exception is using a name that doesn’t match a valid entity class name.

3. Practical Example

Now that we know what causes Hibernate to fail with UnknownEntityException, let’s go down the rabbit hole and see how to reproduce it in practice.

First, let’s consider the Person entity class:

@Entity
public class Person {
    @Id
    private int id;
    private String firstName;
    private String lastName;
    // standard getters and setters
}

In this example, we define a person by their identifier, first name, and last name.

Here, we use the @Entity annotation to indicate that the Person class is a JPA entity. Furthermore, @Id denotes the field that represents the primary key.

Next, we’ll pretend to use the wrong entity name in an HQL query. For instance, let’s try to select all the persons using PERSON as the entity name instead of Person:

class UnknownEntityExceptionUnitTest {
    private static Session session;
    @BeforeAll
    static void init() {
        session = HibernateUtil.getSessionFactory().openSession();
        session.beginTransaction();
    }
    @AfterAll
    static void clear() {
        session.close();
    }
    @Test
    void whenUsingUnknownEntity_thenThrowUnknownEntityException() {
        assertThatThrownBy(() -> session.createQuery("FROM PERSON", Person.class))
          .hasRootCauseInstanceOf(UnknownEntityException.class)
          .hasRootCauseMessage("Could not resolve root entity 'PERSON'");
    }
}

As we can see, the test case fails with UnknownEntityException: Could not resolve root entity because Hibernate doesn’t recognize PERSON as a valid JPA entity.

4. Fixing the Exception

As we noted earlier, the main reason why Hibernate throws UnknownEntityException is that it fails to find an entity with the specified name. So, the easiest solution would be to use the correct entity name in HQL and JPQL queries.

So, let’s add a new test case and replace the wrong name PERSON with Person:

@Test
void whenUsingCorrectEntity_thenReturnResult() {
    Query<Person> query = session.createQuery("FROM Person", Person.class);
    assertThat(query.list()).isEmpty();
}

As shown above, the test case is successfully executed and doesn’t fail with the exception because we used Person this time which is a valid entity name.

5. Conclusion

In this short article, we saw what causes Hibernate to fail with UnknownEntityException: “Could not resolve root entity”. Then, we demonstrated using a practical example how to reproduce the exception and how to solve it.

As always, the full source code of the examples is available over on GitHub.