Introduction

In JPA, the return value for "no matches" depends on which query method you call. The two most important cases are getSingleResult(), which throws an exception when nothing is found, and getResultList(), which returns an empty list.

getSingleResult() does not return null

This is the behavior that surprises many people. If you ask JPA for exactly one result and there is none, JPA throws NoResultException.

1TypedQuery<User> query = entityManager.createQuery(
2    "select u from User u where u.email = :email",
3    User.class
4);
5query.setParameter("email", "[email protected]");
6
7try {
8    User user = query.getSingleResult();
9    System.out.println(user.getEmail());
10} catch (NoResultException ex) {
11    System.out.println("No matching user");
12}

It also throws NonUniqueResultException if more than one row matches. So getSingleResult() is not "return one or return null." It is "return exactly one or fail."

getResultList() returns an empty list

If you want a no-match case that is easy to handle without exceptions, use getResultList().

1TypedQuery<User> query = entityManager.createQuery(
2    "select u from User u where u.active = true",
3    User.class
4);
5
6List<User> users = query.getResultList();
7
8if (users.isEmpty()) {
9    System.out.println("No active users found");
10}

This is often the cleaner choice when zero, one, or many results are all acceptable outcomes.

Choose the API based on semantics

If your domain logic truly requires exactly one match, getSingleResult() expresses that intent. If zero results are normal and not exceptional, getResultList() is usually the better fit.

That distinction matters because exception-driven control flow is awkward when "not found" is part of normal application behavior. A list-based or optional-style API is usually easier to read in those cases.

Repository-style code often wraps this behavior

In higher-level frameworks built on JPA, the raw JPA behavior may be wrapped into more ergonomic return types such as Optional<T> or collection-returning repository methods. But underneath, the same question still exists: is the absence of data exceptional, or is it an expected outcome.

The cleanest code makes that choice explicit in the method signature instead of forcing callers to guess.

Repository methods often make the contract clearer

If your application uses repository abstractions above raw JPA, a method returning Optional<User> communicates the single-or-none case much better than manual exception handling around getSingleResult(). A method returning List<User> communicates zero-or-many just as clearly. Even though the underlying persistence behavior still matters, the higher-level API can make the no-match case easier to reason about.

Do not hide semantics with ad hoc null handling

A common anti-pattern is wrapping JPA query code and converting every no-result situation into null without making that contract explicit. That removes information from the API and makes callers guess whether null means no row, query bug, or some higher-level mapping issue. Clear return semantics are better than a vague sentinel value.

Common Pitfalls

• Expecting getSingleResult() to return null when no rows match.
• Using getSingleResult() when zero matches are normal business behavior.
• Forgetting that getSingleResult() can also fail when more than one row matches.
• Catching broad exceptions instead of handling NoResultException deliberately.
• Using list-returning queries but forgetting to check isEmpty() before reading the first element.

Summary

• 'getSingleResult() throws NoResultException when nothing matches.'
• 'getResultList() returns an empty list when nothing matches.'
• Use the single-result API only when exactly one row is the intended contract.
• Prefer list or optional-style flows when "not found" is a normal case.
• In JPA, the correct no-match handling depends on the query method, not on one universal return rule.