quarkusio/quarkus · error · IllegalArgumentException

Method ${method.name()} of Repository ${repositoryClassInfo}

Error message

Method ${method.name()} of Repository ${repositoryClassInfo}has invalid parameters - only a single parameter of type${DotNames.SPRING_DATA_PAGEABLE} can be specified

What it means

A custom @Query repository method may accept at most one Pageable/PageRequest parameter. Passing a second parameter of type Pageable (or PageRequest) makes parameter binding ambiguous, so the build fails with this IllegalArgumentException.

Source

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

                    || queryString.startsWith("from") || queryString.startsWith("FROM")
                    || queryString.startsWith("delete") || queryString.startsWith("DELETE")
                    || queryString.startsWith("update") || queryString.startsWith("UPDATE"))) {
                throw new IllegalArgumentException("Unsupported query type in @Query. " +
                        "Offending method is " + methodName + " of Repository " + repositoryName);
            }

            List<Type> methodParameterTypes = method.parameterTypes();
            String[] methodParameterTypesStr = new String[methodParameterTypes.size()];
            List<Integer> queryParameterIndexes = new ArrayList<>(methodParameterTypes.size());
            Integer pageableParameterIndex = null;
            Integer sortParameterIndex = null;
            for (int i = 0; i < methodParameterTypes.size(); i++) {
                DotName parameterType = methodParameterTypes.get(i).name();
                methodParameterTypesStr[i] = parameterType.toString();
                if (DotNames.SPRING_DATA_PAGEABLE.equals(parameterType)
                        || DotNames.SPRING_DATA_PAGE_REQUEST.equals(parameterType)) {
                    if (pageableParameterIndex != null) {
                        throw new IllegalArgumentException("Method " + method.name() + " of Repository " + repositoryClassInfo
                                + "has invalid parameters - only a single parameter of type" + DotNames.SPRING_DATA_PAGEABLE
                                + " can be specified");
                    }
                    pageableParameterIndex = i;
                } else if (DotNames.SPRING_DATA_SORT.equals(parameterType)) {
                    if (sortParameterIndex != null) {
                        throw new IllegalArgumentException("Method " + method.name() + " of Repository " + repositoryClassInfo
                                + "has invalid parameters - only a single parameter of type" + DotNames.SPRING_DATA_SORT
                                + " can be specified");
                    }
                    sortParameterIndex = i;
                } else {
                    queryParameterIndexes.add(i);
                }
            }

            // go through the method annotations, find the @Param annotation on parameters
            // and map the name to the method param index

View on GitHub (pinned to e1c734241f)

Solutions

Keep exactly one Pageable/PageRequest parameter and remove the duplicate
If two different pagination behaviors are needed, encode the second one into the query parameters instead (e.g. explicit offset/limit columns or a different method signature)
Use Sort parameters (a single one) if only ordering differs, not two Pageables
Split into two distinct repository methods with clear names

Example fix

// before
List<User> findUsers(Pageable page, Pageable anotherPage);
// after
List<User> findUsers(Pageable page);

Defensive patterns

Strategy: validation

Validate before calling

long pageableCount = Arrays.stream(method.getParameterTypes())
    .filter(t -> Pageable.class.isAssignableFrom(t))
    .count();
if (pageableCount > 1) throw new IllegalArgumentException("At most one Pageable allowed");

Try / catch

try {
    compile();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("only a single parameter of type")) {
        log.error("Remove duplicate Pageable/PageRequest parameter");
    }
    throw e;
}

Prevention

Declare at most one Pageable/PageRequest per repository method
Use Sort (single) for ordering needs
Encode secondary paging into query parameters
Review signatures after copy-paste

When it happens

Trigger: Declaring a repository method with two parameters where both are org.springframework.data.domain.Pageable or PageRequest, e.g. findAll(Pageable p1, Pageable p2) or a @Query method with duplicate pagination parameters.

Common situations: Copy-paste duplication of a pagination parameter; intent to support 'secondary' paging or keyset paging using two Pageables; accidentally importing PageRequest for one param and Pageable for another while semantically meaning the same thing twice.

Related errors

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