quarkusio/quarkus · error · UnableToParseMethodException

Method ${repositoryMethodDescription} cannot be parsed. Did

Error message

Method ${repositoryMethodDescription} cannot be parsed. Did you forget to annotate the method with '@Query'?

What it means

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.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/MethodNameParser.java:95

    public enum QueryType {
        SELECT,
        COUNT,
        EXISTS,
        DELETE;
    }

    public Result parse(MethodInfo methodInfo) {
        String methodName = methodInfo.name();
        ClassInfo repositoryClassInfo = methodInfo.declaringClass();
        String repositoryMethodDescription = "'" + methodName + "' of repository '" + repositoryClassInfo + "'";
        QueryType queryType = getType(methodName);
        String entityAlias = getEntityName().toLowerCase();
        // The SELECT clause is necessary after https://hibernate.atlassian.net/browse/HHH-18584
        String selectClause = queryType == QueryType.SELECT ? "SELECT " + entityAlias + " " : "";
        String fromClause = "FROM " + getEntityName() + " AS " + entityAlias;
        String joinClause = "";
        if (queryType == null) {
            throw new UnableToParseMethodException("Method " + repositoryMethodDescription
                    + " cannot be parsed. Did you forget to annotate the method with '@Query'?");
        }

        int byIndex = methodName.indexOf("By");
        if ((byIndex == -1) || (byIndex + 2 >= methodName.length())) {
            throw new UnableToParseMethodException("Method " + repositoryMethodDescription
                    + " cannot be parsed as there is no proper 'By' clause in the name.");
        }

        // handle 'Top' and 'First'
        Integer topCount = null;
        int minFirstOrTopIndex = Math.min(indexOfOrMaxValue(methodName, "First"), indexOfOrMaxValue(methodName, "Top"));
        // 'First' and 'Top' could be part of a field name, so we only consider them as part of a top query
        // if they are found before 'By'
        if (minFirstOrTopIndex < byIndex) {
            if (queryType != QueryType.SELECT) {
                throw new UnableToParseMethodException(
                        "When 'Top' or 'First' is specified, the query must be a find query. Offending method is "

View on GitHub (pinned to e1c734241f)

Solutions

1. Rename the method to start with a supported keyword, e.g. findBy.../countBy.../deleteBy...
2. Annotate the method with @Query and provide explicit JPQL/HQL
3. Move non-query helper logic out of the repository interface into a service/bean
4. Fix keyword casing — parsing is prefix-based and case-sensitive for these keywords

Example fix

// before
List<User> searchByName(String name);
// after
@Query("FROM User WHERE name = :name")
List<User> searchByName(String name);
// or: List<User> findByName(String name);

// Build-time: every repository method must start with a supported keyword
// or carry @Query:
boolean ok = methodName.matches("(find|get|read|count|delete|exists)By.*")
          || method.isAnnotationPresent(Query.class);

// Error surfaces during Quarkus build, not runtime; fix the repository
// interface so the build passes:
// @Query("FROM User WHERE name = :n") List<User> searchByName(String n);

When it happens

Trigger: 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);`

Common situations: 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.

Related errors

• The number of parameters of method ${method} of Repository $
• Method ${repositoryMethodDescription} cannot be parsed as th
• When 'Top' or 'First' is specified, the query must be a find
• Unable to parse query with limiting results clause. Offendin
• Return type of method ${methodName} of Repository ${reposito

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