quarkusio/quarkus · error · RestClientDefinitionException

Invalid @ClientHeaderParam definition, unable to determine t

Error message

Invalid @ClientHeaderParam definition, unable to determine target method '%s'. Problematic interface: %s

What it means

The @ClientHeaderParam value string did not resolve to a static method on an indexed class, and it also does not match any parameter of the annotated client method. The enricher cannot determine the value target, so it throws at build time.

Source

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

                    Type valueType = null;
                    AtomicInteger parameterPosition = new AtomicInteger(-1);
                    if (headerFillingMethod == null) {
                        for (MethodParameterInfo parameter : declaringMethod.parameters()) {
                            if (!accessibleName.equals(parameter.name())) {
                                continue;
                            }
                            if (!isString(parameter.type())) {
                                throw new RestClientDefinitionException(String.format(
                                        "Invalid %s definition, method parameter %s is not of String type. Problematic interface: %s",
                                        CLIENT_HEADER_PARAM, accessibleName, declaringClass));
                            }
                            accessibleType = AccessibleType.METHOD_PARAMETER;
                            valueType = parameter.type();
                            parameterPosition.set(parameter.position());
                            break;
                        }
                        if (valueType == null) {
                            throw new RestClientDefinitionException(String.format(
                                    "Invalid %s definition, unable to determine target method '%s'. Problematic interface: %s",
                                    CLIENT_HEADER_PARAM, accessibleName, declaringClass));
                        }
                    } else {
                        valueType = headerFillingMethod.returnType();
                    }

                    Supplier<ResultHandle> supplier;
                    if (accessibleType == AccessibleType.STATIC_METHOD) {
                        supplier = new Supplier<ResultHandle>() {
                            @Override
                            public ResultHandle get() {

                                if (headerFillingMethod.parametersCount() == 0) {
                                    return fillHeader.invokeStaticMethod(headerFillingMethod);
                                } else if (headerFillingMethod.parametersCount() == 1
                                        && isString(headerFillingMethod.parameterType(0))) {
                                    return fillHeader.invokeStaticMethod(headerFillingMethod, fillHeader.load(headerName));

View on GitHub (pinned to e1c734241f)

Solutions

1. Make the placeholder exactly match a String parameter name of the client method
2. Ensure the referenced parameter exists (add it or correct the name)
3. If referencing a static method, verify the class is indexed and the reference format is correct

Example fix

// before
@ClientHeaderParam(name = "X-User", value = "{usr}")
String get(@PathParam("id") String userId);
// after
@ClientHeaderParam(name = "X-User", value = "{userId}")
String get(@PathParam("id") String userId);

// Ensure the placeholder matches a parameter name
String value = "{userId}";
String wanted = value.substring(1, value.length() - 1);
boolean found = java.util.Arrays.stream(method.getParameters())
    .anyMatch(p -> p.getName().equals(wanted));
if (!found) throw new IllegalStateException("No parameter " + wanted);

When it happens

Trigger: value="{token}" where no parameter named token exists on the client method (missing @PathParam or wrong name), or a method-name reference whose declaring class lookup failed earlier leaving valueType null.

Common situations: Typos in parameter placeholders, renaming a method parameter without updating the annotation value, or forgetting that the placeholder must exactly match the parameter name.

Related errors

• Duplicate ${annotationName} annotation for parameter: ${name
• Class ${className} used in ${annotationName} on ${declaringC
• ${annotationName} method ${declaringClass}#${staticMethodNam
• ${annotationName} method ${methodName} not found on ${declar
• ${annotationName} method ${declaringClass}#${methodName} has

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