quarkusio/quarkus · error · RestClientDefinitionException

method # has too many parameters, at most one parameter…

Error message

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

What it means

Quarkus REST Client build-time validation error thrown when a @ClientQueryParam/@ClientHeaderParam value method on a class is declared with more than one parameter. Only a zero-arg method or a single String parameter (receiving the header/param name) is allowed, because the generated code calls the method statically with at most the param name.

Solutions

Change the value method to have zero parameters
If the method needs the param/header name, keep exactly one String parameter
Move additional dependencies into static fields or constructor-less helpers

Example fix

// before
class Headers { static String token(String name, String scope) { ... } }
@ClientQueryParam(value = "token", valueFrom = Headers.class)
// after
class Headers { static String token(String name) { ... } }
@ClientQueryParam(value = "token", valueFrom = Headers.class)

Defensive patterns

Strategy: validation

Validate before calling

// Build-time check: ensure each valueFrom static method has 0 params or 1 String param
for (Method m : Values.class.getDeclaredMethods()) {
    if (m.getParameterCount() > 1 || (m.getParameterCount() == 1 && m.getParameterTypes()[0] != String.class))
        throw new IllegalStateException(m + " must take at most one String param");
}

Prevention

Keep value provider methods zero-arg or single String
Add an ArchUnit/unit test asserting valueFrom method signatures
Never add parameters to value-provider methods without checking usages

When it happens

Trigger: Annotating an interface with @ClientQueryParam(value="x", valueFrom=SomeStatic.class) where the referenced static method has 2+ parameters, or one non-String parameter, causing the bytecode generator to fail at build time.

Common situations: Developers write helper methods expecting request context or config objects, or add a second parameter for convenience, then the Quarkus build fails with RestClientDefinitionException.

Related errors

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

Appendix: source

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

            if (methodName.contains(".")) {
                // calling a static method
                int endOfClassName = methodName.lastIndexOf('.');
                String className = methodName.substring(0, endOfClassName);
                String staticMethodName = methodName.substring(endOfClassName + 1);

                ClassInfo clazz = index.getClassByName(DotName.createSimple(className));
                if (clazz == null) {
                    throw new RestClientDefinitionException(
                            "Class " + className + " used in " + annotationName + " on " + declaringClass + " not found");
                }
                paramValueMethod = findMethod(clazz, declaringClass, staticMethodName, clientParamAnnotation.toString());

                if (paramValueMethod.parametersCount() == 0) {
                    paramValue = methodCallCreator.invokeStaticMethod(paramValueMethod);
                } else if (paramValueMethod.parametersCount() == 1 && isString(paramValueMethod.parameterType(0))) {
                    paramValue = methodCallCreator.invokeStaticMethod(paramValueMethod, methodCallCreator.load(paramName));
                } else {
                    throw new RestClientDefinitionException(
                            annotationName + " method " + declaringClass.toString() + "#" + staticMethodName
                                    + " has too many parameters, at most one parameter, param name, expected");
                }
            } 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))) {

View on GitHub (pinned to e1c734241f)