quarkusio/quarkus · error · IllegalArgumentException

${method.name()} of Repository ${repositoryClassInfo} is mis

Error message

${method.name()} of Repository ${repositoryClassInfo} is missing the named parameters ${missingParameters}, provided are ${namedParameterToIndex.keySet()}. Ensure that the parameters are correctly annotated with @Param.

What it means

When a @Query uses named parameters (:name syntax), every named parameter must be bound to a Java method parameter annotated with @Param("name"). Quarkus extracts the named parameters from the query string at build time and fails with this IllegalArgumentException if any used :param has no matching @Param-annotated method parameter.

Source

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

                        namedParameterToIndex.put(parameterName, index);
                    }
                }
            }

            boolean isModifying = (method.annotation(DotNames.SPRING_DATA_MODIFYING) != null);
            if (isModifying && (sortParameterIndex != null || pageableParameterIndex != null)) {
                throw new IllegalArgumentException(
                        method.name() + " of Repository " + repositoryClassInfo
                                + " is meant to be a insert/update/delete query and therefore doesn't " +
                                "support Pageable and Sort method parameters");
            }

            Set<String> usedNamedParameters = extractNamedParameters(queryString);
            if (!usedNamedParameters.isEmpty()) {
                Set<String> missingParameters = new LinkedHashSet<>(usedNamedParameters);
                missingParameters.removeAll(namedParameterToIndex.keySet());
                if (!missingParameters.isEmpty()) {
                    throw new IllegalArgumentException(
                            method.name() + " of Repository " + repositoryClassInfo
                                    + " is missing the named parameters " + missingParameters
                                    + ", provided are " + namedParameterToIndex.keySet()
                                    + ". Ensure that the parameters are correctly annotated with @Param.");
                }
                namedParameterToIndex.keySet().retainAll(usedNamedParameters);
            } else {
                namedParameterToIndex.clear();
            }

            DotName methodReturnTypeDotName = method.returnType().name();

            // Need effectively final copies for use in lambdas
            final Integer finalPageableParameterIndex = pageableParameterIndex;
            final Integer finalSortParameterIndex = sortParameterIndex;
            final String finalQueryString = queryString;
            final Map<String, Integer> finalNamedParameterToIndex = namedParameterToIndex;

View on GitHub (pinned to e1c734241f)

Solutions

Annotate every method parameter with @Param("...") matching exactly the :name used in the query
Fix typos so query parameter names and @Param values match (the message lists missing vs provided names)
Remove leftover :params from the query that no longer have corresponding arguments
Check the error message: it names the missing parameters and the ones actually provided

Example fix

// before
@Query("select u from User u where u.email = :email")
List<User> findByEmail(@Param("mail") String mail);
// after
@Query("select u from User u where u.email = :email")
List<User> findByEmail(@Param("email") String email);

Defensive patterns

Strategy: validation

Validate before calling

// Extract :params from query and cross-check @Param annotations
Set<String> used = new HashSet<>();
Matcher m = Pattern.compile(":(\w+)").matcher(query);
while (m.find()) used.add(m.group(1));
Set<String> provided = new HashSet<>();
for (Annotation[] as : method.getParameterAnnotations())
    for (Annotation a : as)
        if (a instanceof Param p) provided.add(p.value());
if (!provided.containsAll(used))
    throw new IllegalArgumentException("Missing @Param for: " + new HashSet<>(used) .stream().filter(p -> !provided.contains(p)).toList());

Try / catch

try {
    compile();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("missing the named parameters")) {
        log.error("Align :names with @Param values: " + e.getMessage());
    }
    throw e;
}

Prevention

Always annotate query method parameters with @Param matching :names exactly
Rename query and @Param together
Remove unused :params from queries
The error lists missing vs provided — use it to spot typos

When it happens

Trigger: A JPQL query references :foo but no method parameter is annotated @Param("foo"); parameter names differ from query names (e.g. :email vs @Param("mail")); relying on -parameters compiler flag/Java 8 name retention that Quarkus's Spring Data layer does not pick up; a typo in the query introduces an unused named parameter.

Common situations: Renaming a query parameter in JPQL but not the @Param annotation; copy-pasted queries where one parameter was removed from the signature but not the query string; forgetting @Param entirely because plain Spring sometimes infers names from bytecode.

Related errors

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