quarkusio/quarkus · error · RestClientDefinitionException

${annotationName} method ${declaringClass}#${staticMethodNam

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.

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)

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.