{"record":{"id":"fa9d918b687f04c1","repo":"quarkusio/quarkus","slug":"must-be-a-named-query","errorCode":null,"errorMessage":"Must be a named query!","messagePattern":"Must be a named query!","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/AbstractJpaOperations.java","lineNumber":356,"sourceCode":"    }\n\n    public long count(Class<?> entityClass, String query, Parameters params) {\n        return count(entityClass, query, params.map());\n    }\n\n    private SelectionQuery<?> extractNamedSelectionQuery(Class<?> entityClass, String query) {\n        String namedQueryName = extractNamedQueryName(entityClass, query);\n        return getSession(entityClass).createNamedSelectionQuery(namedQueryName);\n    }\n\n    private MutationQuery extractNamedMutationQuery(Class<?> entityClass, String query) {\n        String namedQueryName = extractNamedQueryName(entityClass, query);\n        return getSession(entityClass).createNamedMutationQuery(namedQueryName);\n    }\n\n    private String extractNamedQueryName(Class<?> entityClass, String query) {\n        if (!PanacheJpaUtil.isNamedQuery(query))\n            throw new IllegalArgumentException(\"Must be a named query!\");\n\n        String namedQueryName = query.substring(1);\n        NamedQueryUtil.checkNamedQuery(entityClass, namedQueryName);\n        return namedQueryName;\n    }\n\n    public boolean exists(Class<?> entityClass) {\n        return count(entityClass) > 0;\n    }\n\n    public boolean exists(Class<?> entityClass, String query, Object... params) {\n        return count(entityClass, query, params) > 0;\n    }\n\n    public boolean exists(Class<?> entityClass, String query, Map<String, Object> params) {\n        return count(entityClass, query, params) > 0;\n    }\n","sourceCodeStart":338,"sourceCodeEnd":374,"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/AbstractJpaOperations.java#L338-L374","documentation":"extractNamedQueryName is used for mutation operations (update/delete) that must reference a named query. The method validates that the query string starts with '#' (Panache's named-query marker); any other string is rejected with this IllegalArgumentException.","triggerScenarios":"Calling update(\"...\") or delete(\"...\") style operations that route through namedQueryName/extractNamedQueryName with a literal HQL string instead of a '#'-prefixed named query name.","commonSituations":"Confusing the API surface that accepts arbitrary HQL with the named-query-only variant; forgetting the leading '#' when switching from literal HQL to a named query.","solutions":["Prefix the query string with '#' to indicate a named query: update(\"#Person.markInactive\")","Define the mutation as an @NamedQuery on the entity","Use a different API method that accepts literal HQL if a named query is not available"],"exampleFix":"// before\nrepo.update(\"update Person set active = false\");\n// after\nrepo.update(\"#Person.deactivateAll\");","handlingStrategy":"validation","validationCode":"if (!query.startsWith(\"#\")) {\n    throw new IllegalArgumentException(\"This operation only accepts named queries; prefix with '#': #\" + query);\n}","typeGuard":"boolean isNamedQuery(String q) { return q != null && q.startsWith(\"#\"); }","tryCatchPattern":"try {\n    repo.update(query);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().equals(\"Must be a named query!\")) {\n        // use \"#\" + name of an @NamedQuery\n    } else throw e;\n}","preventionTips":["Always prefix named query references with '#'","Define @NamedQuery for all update/delete operations you invoke by name","Distinguish in code review between literal-HQL and named-query APIs"],"tags":["quarkus","panache","named-query","validation"],"backgroundTag":"named-query-syntax-missing-hash","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"}