{"record":{"id":"cfeafcdaedd3b5c9","repo":"quarkusio/quarkus","slug":"the-named-query-namedquery-must-be-defined-on-cfeafc","errorCode":null,"errorMessage":"The named query '${namedQuery}' must be defined on your JPA entity or one of its super classes","messagePattern":"The named query '(.+?)' must be defined on your JPA entity or one of its super classes","errorType":"exception","errorClass":"PanacheQueryException","httpStatus":null,"severity":"error","filePath":"extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/NamedQueryUtil.java","lineNumber":27,"sourceCode":"\nimport io.quarkus.panache.common.exception.PanacheQueryException;\n\npublic final class NamedQueryUtil {\n\n    // will be replaced at augmentation phase\n    private static volatile Map<String, Map<String, String>> namedQueryMap = Collections.emptyMap();\n\n    private NamedQueryUtil() {\n        // prevent initialization\n    }\n\n    public static void setNamedQueryMap(Map<String, Map<String, String>> newNamedQueryMap) {\n        namedQueryMap = newNamedQueryMap;\n    }\n\n    public static void checkNamedQuery(Class<?> entityClass, String namedQuery) {\n        if (!isNamedQuery(entityClass, namedQuery)) {\n            throw new PanacheQueryException(\"The named query '\" + namedQuery +\n                    \"' must be defined on your JPA entity or one of its super classes\");\n        }\n    }\n\n    public static boolean isNamedQuery(Class<?> entityClass, String namedQuery) {\n        Map<String, String> namedQueries = namedQueryMap.get(entityClass.getName());\n        return namedQueries != null && namedQueries.containsKey(namedQuery);\n    }\n\n    private static boolean isNamedQuery(String namedQuery) {\n        for (Map<String, String> namedQueries : namedQueryMap.values()) {\n            if (namedQueries.containsKey(namedQuery)) {\n                return true;\n            }\n        }\n        return false;\n    }\n","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/panache/hibernate-reactive-panache-common/runtime/src/main/java/io/quarkus/hibernate/reactive/panache/common/runtime/NamedQueryUtil.java#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add @NamedQuery(name = \"...\", query = \"...\") on the JPA entity class (or a superclass) exactly matching the referenced name.","Fix the name spelling/case in the find()/list() call to match the declared @NamedQuery name.","Verify the entity class is a Panache entity (extends PanacheEntity or is annotated/registered) so build-time collection includes its named queries.","As a workaround, use the HQL string directly in find(\"...\") instead of a named-query reference."],"exampleFix":"// before\nList<Person> adults = Person.find(\"Adults\").list(); // not defined\n\n// after\n@NamedQuery(name = \"Adults\", query = \"from Person p where p.age >= 18\")\npublic class Person extends PanacheEntity { ... }\n\nList<Person> adults = Person.find(\"Adults\").list();","handlingStrategy":"validation","validationCode":"if (NamedQueryUtil.isNamedQuery(Person.class, \"Adults\")) {\n    Person.find(\"Adults\").list();\n} else {\n    Person.find(\"from Person p where p.age >= 18\").list();\n}","typeGuard":null,"tryCatchPattern":"try { return Person.find(name).list(); } catch (PanacheQueryException e) { log.error(\"Unknown named query: {}\", name, e); throw e; }","preventionTips":["Declare @NamedQuery on the entity class (or a superclass) exactly matching the name used in find()/list()","Centralize named-query names in constants to avoid typos","Add a unit test that resolves every named-query constant via isNamedQuery at startup"],"tags":["panache","jpa","named-query","configuration"],"backgroundTag":"named-query-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}