quarkusio/quarkus · error · UnableToParseMethodException

When 'Top' or 'First' is specified, the query must be a find

Error message

When 'Top' or 'First' is specified, the query must be a find query. Offending method is ${repositoryMethodDescription}.

What it means

'First'/'Top' limiting keywords are only meaningful for find (SELECT) derived queries. If parse() sees First/Top before 'By' but the query type is count/delete/exists, it throws UnableToParseMethodException naming the offending method.

Source

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

        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 "
                                + repositoryMethodDescription + ".");
            }
            try {
                String topCountStr = methodName.substring(minFirstOrTopIndex, byIndex)
                        .replace("Top", "").replace("First", "");
                if (topCountStr.isEmpty()) {
                    topCount = 1;
                } else {
                    topCount = Integer.valueOf(topCountStr);
                }
            } catch (Exception e) {
                throw new UnableToParseMethodException(
                        "Unable to parse query with limiting results clause. Offending method is "
                                + repositoryMethodDescription + ".");
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Remove Top/First from non-find methods; use @Query with setMaxResults or a subquery for limited count/delete
  2. Change the method to a find query if limiting was intended: findTop10By...
  3. Use an explicit @Query and Paginated/limit API instead of name-derived limiting

Example fix

// before
long countTop10ByActive(boolean active);
// after
@Query("select count(u) from User u where u.active = true")
long countActive();
Defensive patterns

Strategy: validation

Validate before calling

// First/Top only allowed on find (SELECT) queries
boolean hasLimit = idx(methodName,"First") < idx(methodName,"By")
                || idx(methodName,"Top") < idx(methodName,"By");
boolean isSelect = methodName.startsWith("find") || methodName.startsWith("get") || methodName.startsWith("read");
if (hasLimit && !isSelect) throw new IllegalStateException("Top/First on non-find method: " + methodName);

Try / catch

// Build-time failure; remove Top/First from count/delete/exists:
// long countByActive(boolean active);

Prevention

When it happens

Trigger: Methods like `long countTop10ByActive(boolean active)` or `deleteFirstByStatus(String s)` — a First/Top keyword appears in the prefix of a non-SELECT derived query.

Common situations: Copy-pasting find-style limiting names onto count/delete methods; misunderstanding that limit applies only to result sets of finds; typos where a field name before 'By' contains First/Top accidentally combined with a non-select type.

Related errors

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