{"record":{"id":"88768dd3363de529","repo":"quarkusio/quarkus","slug":"the-named-query-namedquery-must-be-defined-on","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-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/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-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/NamedQueryUtil.java#L9-L45","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Define the missing @NamedQuery on the entity or one of its superclasses.","Fix the name/typo so it matches a declared named query, including the correct entity-name prefix.","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.","Confirm the class in the prefix is the actual entity name (not the table name)."],"exampleFix":"// before\nPerson.find(\"Person.findByName\", name); // throws if not declared\n\n// after\n@NamedQuery(name = \"Person.findByName\", query = \"from Person p where p.name = ?1\")\n@Entity\npublic class Person extends PanacheEntity { ... }\n// then:\nPerson.find(\"Person.findByName\", name);","handlingStrategy":"validation","validationCode":"if (queryString.contains(\".\") && !hasWhitespace(queryString)) {\n    // treated as named query: verify it exists\n    NamedQueryUtil.checkNamedQuery(Person.class, queryString); // fails fast with same error pre-emptively\n}","typeGuard":null,"tryCatchPattern":"try {\n    return Person.find(queryString, params).list();\n} catch (PanacheQueryException e) {\n    if (e.getMessage().contains(\"must be defined on your JPA entity\")) {\n        // fall back to ad-hoc HQL: Person.find(\"from Person p where p.name = ?1\", name)\n    }\n    throw e;\n}","preventionTips":["Declare every @NamedQuery on the entity or a superclass it extends.","Match the named query prefix to the entity class name exactly.","Remember: a dotted, whitespace-free string is interpreted as a named query.","Add a startup-time smoke test that executes all named queries."],"tags":["panache","jpa","named-query","validation"],"backgroundTag":"named-query-not-defined","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}