quarkusio/quarkus · error · IllegalArgumentException

${method} of Repository ${repository} is meant to be a count

Error message

${method} of Repository ${repository} is meant to be a count query and therefore doesn't support Pageable and Sort method parameters

What it means

Derived count queries (methods named countBy...) produce a single scalar number, so pagination and sorting make no sense for them. The spring-data-jpa extension rejects any countBy method that declares a Sort or Pageable parameter, failing the build with this IllegalArgumentException.

Source

Thrown at extensions/spring-data-jpa/deployment/src/main/java/io/quarkus/spring/data/deployment/generate/DerivedMethodsAdder.java:299

                        }

                        DotName effectiveReturnTypeName = finalReturnType.kind() == Type.Kind.TYPE_VARIABLE ? DotNames.OBJECT
                                : finalReturnType.name();

                        generateFindQueryResultHandling(bc, panacheQuery, finalPageableParameterIndex, params,
                                repositoryClassInfo, entityClassInfo, effectiveReturnTypeName, parseResult.getTopCount(),
                                method.name(), customResultTypeName,
                                entityClassInfo.name().toString(), elementTypeToCast);

                    } else if (parseResult.getQueryType() == MethodNameParser.QueryType.COUNT) {
                        if (!DotNames.PRIMITIVE_LONG.equals(returnType.name())
                                && !DotNames.LONG.equals(returnType.name())) {
                            throw new IllegalArgumentException(
                                    method.name() + " of Repository " + repositoryClassInfo
                                            + " is meant to be a count query and can therefore only have a long return type");
                        }
                        if ((finalSortParameterIndex != null) || finalPageableParameterIndex != null) {
                            throw new IllegalArgumentException(
                                    method.name() + " of Repository " + repositoryClassInfo
                                            + " is meant to be a count query and therefore doesn't " +
                                            "support Pageable and Sort method parameters");
                        }

                        // call JpaOperations.count()
                        Expr count = bc.invokeVirtual(
                                MethodDesc.of(AbstractManagedJpaOperations.class, "count", long.class,
                                        Class.class, String.class, Object[].class),
                                ops, entityClass,
                                Const.of(parseResult.getQuery()), paramsArray);

                        handleLongReturnValue(bc, count, returnType.name());

                    } else if (parseResult.getQueryType() == MethodNameParser.QueryType.EXISTS) {
                        if (!DotNames.PRIMITIVE_BOOLEAN.equals(returnType.name())
                                && !DotNames.BOOLEAN.equals(returnType.name())) {
                            throw new IllegalArgumentException(

View on GitHub (pinned to e1c734241f)

Solutions

Remove the Pageable/Sort parameter from the countBy method
Use the Page repository API instead: a findAll(Pageable) returning Page already exposes getTotalElements/getTotalPages, so no separate pageable count is needed
Split into two methods: one pageable find plus a plain parameterless countBy for totals

Example fix

// before
long countByLastName(String lastName, Pageable pageable);

// after
long countByLastName(String lastName);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure countBy methods take no Pageable/Sort
for (Method m : PersonRepository.class.getDeclaredMethods()) {
    if (m.getName().startsWith("countBy") && Arrays.stream(m.getParameterTypes())
            .anyMatch(t -> Pageable.class.isAssignableFrom(t) || Sort.class.isAssignableFrom(t)))
        throw new IllegalStateException(m.getName() + " must not take Pageable/Sort");
}

Prevention

Use Page<T> findAll(Pageable) for totals instead of paginated counts
Keep count methods parameterized only by filter criteria
Search for 'countBy(.*Pageable' patterns in CI before building

When it happens

Trigger: Declaring e.g. long countByLastName(String lastName, Pageable pageable) or long countByActive(boolean active, Sort sort) — a COUNT query type with finalSortParameterIndex != null or finalPageableParameterIndex != null.

Common situations: Uniformly adding Pageable to every repository method when introducing pagination; copy-paste from a find method that legitimately took Pageable; UI code that wants 'total count for a page' and passes the same Pageable to a count method.

Related errors

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