quarkusio/quarkus · error · PanacheQueryException

The named query '${namedQuery}' must be defined on your JPA

Error message

The named query '${namedQuery}' must be defined on your JPA entity or one of its super classes

What it means

NamedQueryUtil.checkNamedQuery throws PanacheQueryException when a named query is referenced via Panache (e.g. find("NamedQuery")/list("NamedQuery")) but is not registered in the build-time-generated namedQueryMap for the given entity class or its superclasses. Panache validates named queries against the entities at build time, so referencing an unknown name fails fast at runtime. The usual cause is a typo or the @NamedQuery not being declared on the entity (or a superclass) Panache knows about.

Source

Thrown at extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/NamedQueryUtil.java:27

import io.quarkus.panache.common.exception.PanacheQueryException;

public final class NamedQueryUtil {

    // will be replaced at augmentation phase
    private static volatile Map<String, Map<String, String>> namedQueryMap = Collections.emptyMap();

    private NamedQueryUtil() {
        // prevent initialization
    }

    public static void setNamedQueryMap(Map<String, Map<String, String>> newNamedQueryMap) {
        namedQueryMap = newNamedQueryMap;
    }

    public static void checkNamedQuery(Class<?> entityClass, String namedQuery) {
        if (!isNamedQuery(entityClass, namedQuery)) {
            throw new PanacheQueryException("The named query '" + namedQuery +
                    "' must be defined on your JPA entity or one of its super classes");
        }
    }

    public static boolean isNamedQuery(Class<?> entityClass, String namedQuery) {
        Map<String, String> namedQueries = namedQueryMap.get(entityClass.getName());
        return namedQueries != null && namedQueries.containsKey(namedQuery);
    }

    private static boolean isNamedQuery(String namedQuery) {
        for (Map<String, String> namedQueries : namedQueryMap.values()) {
            if (namedQueries.containsKey(namedQuery)) {
                return true;
            }
        }
        return false;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Add @NamedQuery(name = "...", query = "...") on the JPA entity class (or a superclass) exactly matching the referenced name.
2. Fix the name spelling/case in the find()/list() call to match the declared @NamedQuery name.
3. Verify the entity class is a Panache entity (extends PanacheEntity or is annotated/registered) so build-time collection includes its named queries.
4. As a workaround, use the HQL string directly in find("...") instead of a named-query reference.

Example fix

// before
List<Person> adults = Person.find("Adults").list(); // not defined

// after
@NamedQuery(name = "Adults", query = "from Person p where p.age >= 18")
public class Person extends PanacheEntity { ... }

List<Person> adults = Person.find("Adults").list();

if (NamedQueryUtil.isNamedQuery(Person.class, "Adults")) {
    Person.find("Adults").list();
} else {
    Person.find("from Person p where p.age >= 18").list();
}

try { return Person.find(name).list(); } catch (PanacheQueryException e) { log.error("Unknown named query: {}", name, e); throw e; }

When it happens

Trigger: Calling Person.find("SomeNamedQuery") (or list()/stream()/count variants) where SomeNamedQuery is not defined via @NamedQuery on the entity class or one of its superclasses, or the namedQueryMap was not populated with it.

Common situations: Typo in the query name; @NamedQuery placed on a non-entity class or unrelated package; expecting @NamedQuery on an interface to be found; query defined for a different entity; Panache build-time enhancement not scanning the class.

Related errors

• The named query '${namedQuery}' must be defined on your JPA
• Unable to find an EntityManagerFactory for persistence unit
• Entity '%s' was not found. Did you forget to annotate your P
• Sort cannot be used with named query, add an "order by" clau
• Must be a named query!

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/cfeafcdaedd3b5c9. Report an issue: GitHub.