Fixing Hibernate QueryException: Named Parameter Not Bound

Last updated: January 3, 2024

Written by: Abderrahim Azhrioun

Reviewed by: Luis Javier Peris

Persistence

Modern software architecture is often broken. Slow delivery leads to missed opportunities, innovation is stalled due to architectural complexities, and engineering resources are exceedingly expensive.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

With Orkes Conductor managed through Orkes Cloud, developers can focus on building mission critical applications without worrying about infrastructure maintenance to meet goals and, simply put, taking new products live faster and reducing total cost of ownership.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

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.

1. Overview

In this short tutorial, we’ll shed light on how to solve the Hibernate QueryException: “named parameter not bound”.

First, we’ll elucidate the main cause behind the exception. Then, we’ll demonstrate how to reproduce it, and finally, we’ll learn how to fix it.

2. Understanding the Exception

Before jumping to the solution, let’s try to understand what the exception and its stack trace mean.

In short, Hibernate throws QueryException to signal an error when translating a Hibernate query to SQL due to an invalid syntax. Therefore, the stack trace “named parameter not bound” indicates that Hibernate fails to bind a named parameter specified in a particular query.

Typically, a named parameter is prefixed with a colon (:) and followed by a placeholder for the actual value that needs to be set before executing the query:

SELECT p FROM Person p WHERE p.firstName = :firstName;

One of the most common causes of our exception is forgetting to assign a value for a named parameter in a Hibernate query.

3. Reproducing the Exception

Now that we know what is the leading cause of the exception, let’s go down the rabbit hole and see how to reproduce it using a practical example.

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
}

Here, the @Entity annotation denotes that our class is an entity that maps a table in the database. Furthermore, @Id indicates that the id property represents the primary key.

Now, let’s create a Hibernate query with a named parameter and pretend to forget to set a value for our parameter:

@Test
void whenNotSettingValueToNamedParameter_thenThrowQueryException() {
    Exception exception = assertThrows(QueryException.class, () -> {
        Query<Person> query = session.createQuery("FROM Person p WHERE p.firstName = :firstName", Person.class);
        query.list();
    });

    String expectedMessage = "Named parameter not bound";
    String actualMessage = exception.getMessage();

    assertTrue(actualMessage.contains(expectedMessage));
}

As we can see, the test case fails with QueryException: “named parameter not bound”. The reason here is that Hibernate doesn’t know anything about the named parameter firstName and expects this parameter to be set before executing the query.

4. Fixing the Exception

The solution to avoid QueryException in this case is to assign a value to the named parameter before executing the query. To do so, we can use the setParameter() method:

@Test
void whenSettingValueToNamedParameter_thenDoNotThrowQueryException() {
    Query<Person> query = session.createQuery("FROM Person p WHERE p.firstName = :firstName", Person.class);
    query.setParameter("firstName", "Azhrioun");

    assertNotNull(query.list());
}

As shown above, the test case passes with success. The setParameter() call tells Hibernate which value to use for our named parameter when executing the query.

5. Conclusion

In this short article, we explained what causes Hibernate to throw QueryException: “named parameter not bound”. Then, we illustrated using a practical example how to reproduce the exception and how to fix 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.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Orkes is the leading workflow orchestration platform built to enable teams to transform the way they develop, connect, and deploy applications, microservices, AI agents, and more.

Try a 14-Day Free Trial of Orkes Conductor today.

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.