Solving Hibernate SyntaxException: token ‘*’, no viable alternative at input

1. Overview

Understanding common errors when using Hibernate can be critical for debugging, but also for better coding practices. Part of this understanding involves knowing the difference between different environments and syntactic rules. For instance, when attempting to select multiple entries, we might be inclined to use an * asterisk. However, assumptions can lead us astray in some cases.

In this short tutorial, we’ll walk through how to fix the Hibernate exception SyntaxException: token ‘*’, no viable alternative at input. First of all, we’ll break down what causes Hibernate to fail with this exception. Then, with simple examples, we’ll see how to reproduce it, and most importantly, how to solve it.

2. Using SELECT *

In general, a SyntaxException usually means Hibernate couldn’t understand a given query due to the way it was written. Hibernate expects queries to follow a precise syntax. If it sees something unexpected, interpretation fails, and Hibernate throws a SyntaxException.

For example, we often use SELECT * FROM Table to select all data in SQL. However, in this case, HQL throws SyntaxException: “token ‘*’, no viable alternative at input”.

The issue here isn’t that Hibernate fails to grasp the idea of fetching all columns. The misunderstanding comes from the fact that HQL works with objects and fields instead of tables and columns. This is why there is no literal * in HQL.

3. Reproducing SyntaxException

Now that we know what causes SyntaxException, we should be able to reproduce it.

To that end, let’s consider a Person JPA entity class:

@Entity
public class Person {

    @Id
    private int id;
    private String firstName;
    private String lastName;

}

Simply put, every person has an ID, a first name, and a last name. The @Entity annotation tells JPA that the Person class is an entity, while @Id marks its primary key. On top of that, the @Column annotation maps each field to its matching column in the database.

Now, let’s attempt to use * in an HQL query to get all the data and see what happens:

class SyntaxExceptionUnitTest {

    private static Session session;

    @BeforeAll
    static void beforeAll() {
        session = HibernateUtil.getSessionFactory()
          .openSession();
        session.beginTransaction();
    }

    @AfterAll
    static void afterAll() {
        session.close();
    }

    @Test
    void whenUsingInvalidHQLSyntax_thenThrowSyntaxException() {
        assertThatThrownBy(() -> {
            session.createQuery("SELECT * FROM Person p", Person.class)
              .list();
        }).hasRootCauseInstanceOf(SyntaxException.class)
          .hasMessageContaining("token '*', no viable alternative");
    }
}

As we can see, trying to use SELECT * in HQL makes Hibernate fail with SyntaxException: token ‘*’, no viable alternative at input.

As we mentioned, Hibernate doesn’t know what * means because it operates at a higher level of abstraction. Its queries are centered around entities and their mapped fields, rather than tables and columns.

4. Correcting With SELECT p

HQL doesn’t interpret the asterisk symbol in the same way as SQL because of fundamental differences in their design and underlying paradigms. Again, SQL works with tables and columns, unlike HQL, which works with objects and properties.

That’s why HQL syntax is different. Instead of asking for the * symbol that denotes all columns in SQL, we query the entity itself. So, the most straightforward solution is to use a valid HQL syntax to fetch all Person entities:

@Test
void whenUsingValidHQLSyntax_thenCorrect() {
    Person person = new Person(1, "Jane", "Austen");
    session.persist(person);
        
    List<Person> personList = session.createQuery("SELECT p FROM Person p", Person.class).list();
        
    assertThat(personList).contains(person);
}

As shown above, we can use an alias like p for the Person entity to denote that we want to select the whole entity object. We can think of it like a shortcut, so we can refer to the Person fields later.

Notably, HQL provides another syntactic shortcut to write the same query without using the alias in case we want to select all data:

session.createQuery("FROM Person", Person.class)

In short, we can omit the SELECT clause altogether.

5. Conclusion

In this short article, we explained why Hibernate throws SyntaxException: token ‘*’, no viable alternative at input. Then, we walked through an example to reproduce the exception and wrapped up with a practical solution to fix it.

The full source is available over on GitHub.