How to Fix Hibernate UnknownEntityException: Could not resolve root entity

Last updated: July 5, 2024

Written by: Abderrahim Azhrioun

Reviewed by: Luis Javier Peris

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Regression testing is an important step in the release process, to ensure that new code doesn't break the existing functionality. As the codebase evolves, we want to run these tests frequently to help catch any issues early on.

The best way to ensure these tests run frequently on an automated basis is, of course, to include them in the CI/CD pipeline. This way, the regression tests will execute automatically whenever we commit code to the repository.

In this tutorial, we'll see how to create regression tests using Selenium, and then include them in our pipeline using GitHub Actions:, to be run on the LambdaTest cloud grid:

>> How to Run Selenium Regression Tests With GitHub Actions

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.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.