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_SORT} can be specified

What it means

Similar to the Pageable restriction: a custom @Query method can declare at most one Sort parameter. Two Sort parameters make ordering binding ambiguous, and the augmentation step rejects the method with this IllegalArgumentException.

Source

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

            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
            Map<String, Integer> namedParameterToIndex = new HashMap<>();
            for (AnnotationInstance annotation : method.annotations(DotNames.SPRING_DATA_PARAM)) {
                var index = (int) annotation.target().asMethodParameter().position();
                namedParameterToIndex.put(annotation.value().asString(), index);
            }
            // if no or only some parameters are annotated with @Param, add the compiled names (if present)
            if (namedParameterToIndex.size() < methodParameterTypes.size()) {

View on GitHub (pinned to e1c734241f)

Solutions

Use a single Sort parameter and chain multiple orders with Sort.by(Order.desc("a"), Order.asc("b"))
Remove the redundant Sort parameter
If two independent sort needs exist, define two separate repository methods
Embed fixed ordering directly into the JPQL (ORDER BY) and keep only dynamic sorting in one Sort parameter

Example fix

// before
List<User> findUsers(Sort primarySort, Sort secondarySort);
// after
List<User> findUsers(Sort sort);
// caller: Sort.by(Order.desc("created"), Order.asc("name"))

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    compile();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("only a single parameter of type")) {
        log.error("Merge multiple Sort objects into one Sort.by(...)");
    }
    throw e;
}

Prevention

Use a single Sort parameter; combine orders with Sort.by(Order...)
Put fixed ordering in JPQL ORDER BY
Avoid passing two Sorts for multi-column ordering
Lint repository interfaces for duplicate Sort parameters

When it happens

Trigger: Declaring a repository method with two parameters of type org.springframework.data.domain.Sort, e.g. findByX(Sort primary, Sort secondary) or combining a redundant sort alongside another Sort.

Common situations: Trying to express multi-column ordering by passing two Sort objects (Spring merges them into one Sort anyway); copy-paste errors in method signatures; refactoring a method that already had Sort and adding another one.

Related errors

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