quarkusio/quarkus · error · RestClientDefinitionException

Method ${class}#${method} has an unsupported return type for

Error message

Method ${class}#${method} has an unsupported return type for ClientHeaderParam. Only String is supported when using complex expressions

What it means

When the ClientHeaderParam value is a 'complex expression' (a mix of literal text and multiple expressions producing more than one parsed node), the generated bytecode concatenates each node's value with StringBuilder, which only works with String. The referenced method must therefore return String exactly; String[] cannot be appended, so the build fails with RestClientDefinitionException.

Source

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

                                return fillHeader.invokeStaticMethod(COMPUTER_PARAM_CONTEXT_IMPL_GET_METHOD_PARAM,
                                        requestContext, fillHeader.load(parameterPosition.get()));
                            }
                        };
                    } else {
                        throw new IllegalStateException("Unknown type " + accessibleType);
                    }

                    if (nodes.size() == 1) {
                        if (!isString(valueType) && !isStringArray(
                                valueType)) {
                            throw new RestClientDefinitionException("Method " + headerFillingMethod.declaringClass().toString()
                                    + "#" + headerFillingMethod.name()
                                    + " has an unsupported return type for ClientHeaderParam. " +
                                    "Only String and String[] return types are supported");
                        }
                    } else {
                        if (!isString(valueType)) {
                            throw new RestClientDefinitionException("Method " + headerFillingMethod.declaringClass().toString()
                                    + "#" + headerFillingMethod.name()
                                    + " has an unsupported return type for ClientHeaderParam. " +
                                    "Only String is supported when using complex expressions");
                        }
                    }

                    return new HeaderFillerInfo(valueType, n, supplier);

                } else {
                    throw new IllegalStateException("Unknown node type " + n.getClass().getName());
                }
            }).collect(Collectors.toList());

            AssignableResultHandle headerList = fillHeader.createVariable(List.class);
            fillHeader.assign(headerList, fillHeader.loadNull());
            if (headerFillerInfos.size() == 1) {
                HeaderFillerInfo headerFillerInfo = headerFillerInfos.get(0);
                ResultHandle headerFillerResult = headerFillerInfo.getResultHandleSupplier().get();

View on GitHub (pinned to e1c734241f)

Solutions

Change the referenced method's return type to String
If you need multiple values, drop the surrounding literal text and use a single-expression value with String[] return type
Convert the array/collection to a joined String in the method itself (String.join(...))

Example fix

// before
@ClientHeaderParam(name="Authorization", value="Bearer {getToken}")
String[] getToken() { ... }

// after
@ClientHeaderParam(name="Authorization", value="Bearer {getToken}")
String getToken() { return String.join(",", tokens); }

Defensive patterns

Strategy: validation

Validate before calling

// Complex (multi-node) expressions require String return
Method m = MyClient.class.getDeclaredMethod("getToken");
boolean complex = annotationValue().contains("-") || annotationValue().contains("${");
if (complex && m.getReturnType() != String.class) {
    throw new IllegalStateException("Complex ClientHeaderParam expressions require String return: " + m);
}

Type guard

static boolean stringOnly(Class<?> t) { return t == String.class; }

Prevention

Use String[] return only with a single whole-value expression, never inside composite values
Join arrays into a single String when embedding into composite header text
Document the return-type rule on shared header-provider utility methods

When it happens

Trigger: @ClientHeaderParam(name="X", value="prefix-{token}-v${version}") where the referenced method(s) resolve to a non-String return type (including String[]). Only multi-node (complex) values trigger this branch.

Common situations: Building composite header strings like 'Bearer {jwt}' or 'key:version' where the token-computation method returns String[] (left over from a previous single-expression usage) or a primitive.

Related errors

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