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 and String[] return types are supported

What it means

During REST client build-time bytecode generation, Quarkus validates that the method referenced by @ClientHeaderParam returns a type it can turn into header value(s). When the ClientHeaderParam value contains a single expression (one node), only String or String[] returns can be converted into header values, so anything else fails the build with RestClientDefinitionException. This is a deployment-time validation, not a runtime failure.

Source

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

                                }
                            }
                        };
                    } else if (accessibleType == AccessibleType.METHOD_PARAMETER) {
                        supplier = new Supplier<ResultHandle>() {
                            @Override
                            public ResultHandle get() {
                                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());
                }

View on GitHub (pinned to e1c734241f)

Solutions

Change the referenced method's return type to String or String[]
If returning a collection, convert to String[] inside the method (e.g. list.toArray(new String[0])) or join into a single String
If returning Optional, unwrap with orElse(null)/orElseThrow in the method

Example fix

// before
@ClientHeaderParam(name="X-Request-Ids", value="{computeIds}")
List<String> computeIds() { return ids; }

// after
@ClientHeaderParam(name="X-Request-Ids", value="{computeIds}")
String[] computeIds() { return ids.toArray(new String[0]); }

Defensive patterns

Strategy: validation

Validate before calling

// Before building, assert the referenced method returns String/String[]
Method m = MyClient.class.getDeclaredMethod("computeIds");
if (!(m.getReturnType() == String.class || m.getReturnType() == String[].class)) {
    throw new IllegalStateException("@ClientHeaderParam method must return String or String[]: " + m);
}

Type guard

static boolean validHeaderReturn(Class<?> t) {
    return t == String.class || t == String[].class;
}

Prevention

Keep all @ClientHeaderParam provider methods returning String or String[]
Convert collections/Optionals to String/String[] inside the provider method
Run the application build (not just compile) before release; these errors surface at Quarkus deployment

When it happens

Trigger: Annotating a client interface method with @ClientHeaderParam(name="X", value="{myMethod}") where myMethod resolves (static method, interface default method, or method-parameter reference) to a return type other than String/String[] (e.g. int, List<String>, Optional<String>) and the value expression contains exactly one node.

Common situations: Developers returning numeric IDs, enums or collections from header-computation methods, or refactoring a String[] method to List<String> assuming collections are supported.

Related errors

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