{"record":{"id":"7b901cdfec093f22","repo":"quarkusio/quarkus","slug":"method-class-method-has-an-unsupported-retur","errorCode":null,"errorMessage":"Method ${class}#${method} has an unsupported return type for ClientHeaderParam. Only String and String[] return types are supported","messagePattern":"Method (.+?)#(.+?) has an unsupported return type for ClientHeaderParam\\. Only String and String\\[\\] return types are supported","errorType":"exception","errorClass":"RestClientDefinitionException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/MicroProfileRestClientEnricher.java","lineNumber":961,"sourceCode":"                                }\n                            }\n                        };\n                    } else if (accessibleType == AccessibleType.METHOD_PARAMETER) {\n                        supplier = new Supplier<ResultHandle>() {\n                            @Override\n                            public ResultHandle get() {\n                                return fillHeader.invokeStaticMethod(COMPUTER_PARAM_CONTEXT_IMPL_GET_METHOD_PARAM,\n                                        requestContext, fillHeader.load(parameterPosition.get()));\n                            }\n                        };\n                    } else {\n                        throw new IllegalStateException(\"Unknown type \" + accessibleType);\n                    }\n\n                    if (nodes.size() == 1) {\n                        if (!isString(valueType) && !isStringArray(\n                                valueType)) {\n                            throw new RestClientDefinitionException(\"Method \" + headerFillingMethod.declaringClass().toString()\n                                    + \"#\" + headerFillingMethod.name()\n                                    + \" has an unsupported return type for ClientHeaderParam. \" +\n                                    \"Only String and String[] return types are supported\");\n                        }\n                    } else {\n                        if (!isString(valueType)) {\n                            throw new RestClientDefinitionException(\"Method \" + headerFillingMethod.declaringClass().toString()\n                                    + \"#\" + headerFillingMethod.name()\n                                    + \" has an unsupported return type for ClientHeaderParam. \" +\n                                    \"Only String is supported when using complex expressions\");\n                        }\n                    }\n\n                    return new HeaderFillerInfo(valueType, n, supplier);\n\n                } else {\n                    throw new IllegalStateException(\"Unknown node type \" + n.getClass().getName());\n                }","sourceCodeStart":943,"sourceCodeEnd":979,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/MicroProfileRestClientEnricher.java#L943-L979","documentation":"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.","triggerScenarios":"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.","commonSituations":"Developers returning numeric IDs, enums or collections from header-computation methods, or refactoring a String[] method to List<String> assuming collections are supported.","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"],"exampleFix":"// before\n@ClientHeaderParam(name=\"X-Request-Ids\", value=\"{computeIds}\")\nList<String> computeIds() { return ids; }\n\n// after\n@ClientHeaderParam(name=\"X-Request-Ids\", value=\"{computeIds}\")\nString[] computeIds() { return ids.toArray(new String[0]); }","handlingStrategy":"validation","validationCode":"// Before building, assert the referenced method returns String/String[]\nMethod m = MyClient.class.getDeclaredMethod(\"computeIds\");\nif (!(m.getReturnType() == String.class || m.getReturnType() == String[].class)) {\n    throw new IllegalStateException(\"@ClientHeaderParam method must return String or String[]: \" + m);\n}","typeGuard":"static boolean validHeaderReturn(Class<?> t) {\n    return t == String.class || t == String[].class;\n}","tryCatchPattern":null,"preventionTips":["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"],"tags":["quarkus","rest-client","build-time","annotation-validation","clientheaderparam"],"backgroundTag":"unsupported-return-type","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}