quarkusio/quarkus · error · RestClientDefinitionException

${annotationName} method ${declaringClass}#${methodName} has

Error message

${annotationName} method ${declaringClass}#${methodName} has too many parameters, at most one parameter, param name, expected

What it means

Same constraint as the static-method variant but for interface-based value methods: when @ClientQueryParam/@ClientHeaderParam points to a method on an interface, the resolved method must have zero parameters or exactly one String parameter (the param name). Anything else fails client generation at build time.

Source

Thrown at extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/MicroProfileRestClientEnricher.java:458

            } else {
                // interface method
                String mockName = mockInterface(declaringClass, generatedClasses, index);
                ResultHandle interfaceMock = methodCallCreator.newInstance(MethodDescriptor.ofConstructor(mockName));

                paramValueMethod = findMethod(declaringClass, declaringClass, methodName, clientParamAnnotation.toString());

                if (paramValueMethod == null) {
                    throw new RestClientDefinitionException(
                            annotationName + " method " + methodName + " not found on " + declaringClass);
                }

                if (paramValueMethod.parametersCount() == 0) {
                    paramValue = methodCallCreator.invokeInterfaceMethod(paramValueMethod, interfaceMock);
                } else if (paramValueMethod.parametersCount() == 1 && isString(paramValueMethod.parameterType(0))) {
                    paramValue = methodCallCreator.invokeInterfaceMethod(paramValueMethod, interfaceMock,
                            methodCallCreator.load(paramName));
                } else {
                    throw new RestClientDefinitionException(
                            annotationName + " method " + declaringClass + "#" + methodName
                                    + " has too many parameters, at most one parameter, param name, expected");
                }

            }

            Type returnType = paramValueMethod.returnType();
            ResultHandle valuesList;
            if (isStringArray(returnType)) {
                // repack array to list
                valuesList = methodCallCreator.invokeStaticMethod(ARRAYS_AS_LIST, paramValue);
            } else if (isString(returnType)) {
                valuesList = methodCallCreator.newInstance(MethodDescriptor.ofConstructor(ArrayList.class));
                methodCallCreator.invokeInterfaceMethod(LIST_ADD_METHOD, valuesList, paramValue);
            } else {
                throw new RestClientDefinitionException("Method " + declaringClass.toString() + "#" + methodName
                        + " has an unsupported return type for " + annotationName + ". " +
                        "Only String and String[] return types are supported");

View on GitHub (pinned to e1c734241f)

Solutions

Reduce the interface method to zero parameters or one String parameter
Overload: keep a rich method internally but expose a zero/String-arg method for the annotation
Use a static class-based valueFrom instead if more context is needed

Example fix

// before
interface Values { String token(String name, String scope); }
// after
interface Values { String token(String name); }

Defensive patterns

Strategy: validation

Validate before calling

for (Method m : Values.class.getDeclaredMethods()) {
    if (m.getParameterCount() > 1 || (m.getParameterCount() == 1 && m.getParameterTypes()[0] != String.class))
        throw new IllegalStateException(m + " invalid signature for @ClientQueryParam valueFrom");
}

Prevention

Document the allowed signature (0 args or 1 String) on provider interfaces
Add overload shims when evolving interfaces
Review interface changes with annotation usages in mind

When it happens

Trigger: valueFrom interface method declared with 2+ parameters, or a single non-String parameter (e.g. int, URI), when the enricher generates the mock interface call.

Common situations: Interface evolved to add parameters (e.g. adding a config or context argument); build now fails for every client using that interface.

Related errors

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