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

When a string passed to find()/list() methods is treated as a named query, Panache validates at build time against the generated named-query map. checkNamedQuery() throws PanacheQueryException if the named query is not registered on the entity or any of its superclasses.

Source

Thrown at extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/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. Define the missing @NamedQuery on the entity or one of its superclasses.
2. Fix the name/typo so it matches a declared named query, including the correct entity-name prefix.
3. If you meant an ad-hoc HQL query, pass a query string containing a space or 'from'/'select' so it is not treated as a named query.
4. Confirm the class in the prefix is the actual entity name (not the table name).

Example fix

// before
Person.find("Person.findByName", name); // throws if not declared

// after
@NamedQuery(name = "Person.findByName", query = "from Person p where p.name = ?1")
@Entity
public class Person extends PanacheEntity { ... }
// then:
Person.find("Person.findByName", name);

if (queryString.contains(".") && !hasWhitespace(queryString)) {
    // treated as named query: verify it exists
    NamedQueryUtil.checkNamedQuery(Person.class, queryString); // fails fast with same error pre-emptively
}

try {
    return Person.find(queryString, params).list();
} catch (PanacheQueryException e) {
    if (e.getMessage().contains("must be defined on your JPA entity")) {
        // fall back to ad-hoc HQL: Person.find("from Person p where p.name = ?1", name)
    }
    throw e;
}

When it happens

Trigger: Calling Person.find("Person.findByName", ...) (or list/count/stream variants) where "Person.findByName" was never declared with @NamedQuery on the entity or a superclass, or the entity name prefix does not match.

Common situations: Typos in the named query name; declaring @NamedQuery on a class not in the entity hierarchy; using the wrong entity prefix; forgetting that a dotted name triggers named-query lookup instead of ad-hoc HQL.

Related errors

• Must be a named query!
• The named query '${namedQuery}' must be defined on your JPA
• Query string cannot be empty
• Sort column name cannot have backticks
• The annotation ProjectedFieldName must have a non-empty valu

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