{"record":{"id":"babb60470969b51c","repo":"quarkusio/quarkus","slug":"method-repositorymethoddescription-cannot-be-pa","errorCode":null,"errorMessage":"Method ${repositoryMethodDescription} cannot be parsed. Did you forget to annotate the method with '@Query'?","messagePattern":"Method (.+?) cannot be parsed\\. Did you forget to annotate the method with '@Query'\\?","errorType":"exception","errorClass":"UnableToParseMethodException","httpStatus":null,"severity":"error","filePath":"extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/MethodNameParser.java","lineNumber":95,"sourceCode":"    public enum QueryType {\n        SELECT,\n        COUNT,\n        EXISTS,\n        DELETE;\n    }\n\n    public Result parse(MethodInfo methodInfo) {\n        String methodName = methodInfo.name();\n        ClassInfo repositoryClassInfo = methodInfo.declaringClass();\n        String repositoryMethodDescription = \"'\" + methodName + \"' of repository '\" + repositoryClassInfo + \"'\";\n        QueryType queryType = getType(methodName);\n        String entityAlias = getEntityName().toLowerCase();\n        // The SELECT clause is necessary after https://hibernate.atlassian.net/browse/HHH-18584\n        String selectClause = queryType == QueryType.SELECT ? \"SELECT \" + entityAlias + \" \" : \"\";\n        String fromClause = \"FROM \" + getEntityName() + \" AS \" + entityAlias;\n        String joinClause = \"\";\n        if (queryType == null) {\n            throw new UnableToParseMethodException(\"Method \" + repositoryMethodDescription\n                    + \" cannot be parsed. Did you forget to annotate the method with '@Query'?\");\n        }\n\n        int byIndex = methodName.indexOf(\"By\");\n        if ((byIndex == -1) || (byIndex + 2 >= methodName.length())) {\n            throw new UnableToParseMethodException(\"Method \" + repositoryMethodDescription\n                    + \" cannot be parsed as there is no proper 'By' clause in the name.\");\n        }\n\n        // handle 'Top' and 'First'\n        Integer topCount = null;\n        int minFirstOrTopIndex = Math.min(indexOfOrMaxValue(methodName, \"First\"), indexOfOrMaxValue(methodName, \"Top\"));\n        // 'First' and 'Top' could be part of a field name, so we only consider them as part of a top query\n        // if they are found before 'By'\n        if (minFirstOrTopIndex < byIndex) {\n            if (queryType != QueryType.SELECT) {\n                throw new UnableToParseMethodException(\n                        \"When 'Top' or 'First' is specified, the query must be a find query. Offending method is \"","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/MethodNameParser.java#L77-L113","documentation":"At build time, Quarkus' Spring Data JPA extension parses derived-query repository method names. MethodNameParser.parse() throws UnableToParseMethodException when the method has no recognizable query type (find/read/get/count/delete/exists) prefix, so no JPQL can be derived — the hint points to using an explicit @Query instead.","triggerScenarios":"A repository method whose name starts with none of the supported keywords (findBy, getBy, readBy, countBy, deleteBy, existsBy...) and is not annotated with @Query, e.g. `List<User> all();` or `List<User> searchByName(String n);`","commonSituations":"Migrating Spring Data repos where custom methods relied on @Query that was removed; typos like `findbyName` or `FindByName`; helper methods declared in the repository interface.","solutions":["Rename the method to start with a supported keyword, e.g. findBy.../countBy.../deleteBy...","Annotate the method with @Query and provide explicit JPQL/HQL","Move non-query helper logic out of the repository interface into a service/bean","Fix keyword casing — parsing is prefix-based and case-sensitive for these keywords"],"exampleFix":"// before\nList<User> searchByName(String name);\n// after\n@Query(\"FROM User WHERE name = :name\")\nList<User> searchByName(String name);\n// or: List<User> findByName(String name);","handlingStrategy":"validation","validationCode":"// Build-time: every repository method must start with a supported keyword\n// or carry @Query:\nboolean ok = methodName.matches(\"(find|get|read|count|delete|exists)By.*\")\n          || method.isAnnotationPresent(Query.class);","typeGuard":null,"tryCatchPattern":"// Error surfaces during Quarkus build, not runtime; fix the repository\n// interface so the build passes:\n// @Query(\"FROM User WHERE name = :n\") List<User> searchByName(String n);","preventionTips":["Name all derived methods find/get/read/count/delete/exists + By...","Annotate any custom-named method with @Query","Watch for casing typos like findbyName","Keep helper methods out of repository interfaces"],"tags":["spring-data-jpa","build-time","derived-query","quarkus"],"backgroundTag":"unparseable-repository-method","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"}