{"record":{"id":"331c7ca5f227bd8e","repo":"quarkusio/quarkus","slug":"registerclientcontextresolver-is-only-supported-o","errorCode":null,"errorMessage":"@RegisterClientContextResolver is only supported on static methods of REST Client interfaces that return '${expectedReturnType}'. Offending instance is '${className}#${methodName}'","messagePattern":"@RegisterClientContextResolver is only supported on static methods of REST Client interfaces that return '(.+?)'\\. Offending instance is '(.+?)#(.+?)'","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/ClientContextResolverHandler.java","lineNumber":99,"sourceCode":"    GeneratedClassResult generateContextResolver(AnnotationInstance instance) {\n        if (!annotation.equals(instance.name())) {\n            throw new IllegalArgumentException(\n                    \"'clientContextResolverInstance' must be an instance of \" + annotation);\n        }\n        MethodInfo targetMethod = findTargetMethod(instance);\n        if (targetMethod == null) {\n            return null;\n        }\n\n        int priority = Priorities.USER;\n        AnnotationValue priorityAnnotationValue = instance.value(\"priority\");\n        if (priorityAnnotationValue != null) {\n            priority = priorityAnnotationValue.asInt();\n        }\n\n        Class<?> returnTypeClassName = lookupReturnClass(targetMethod);\n        if (!expectedReturnType.isAssignableFrom(returnTypeClassName)) {\n            throw new IllegalStateException(annotation\n                    + \" is only supported on static methods of REST Client interfaces that return '\" + expectedReturnType + \"'.\"\n                    + \" Offending instance is '\" + targetMethod.declaringClass().name().toString() + \"#\"\n                    + targetMethod.name() + \"'\");\n        }\n\n        ClassInfo restClientInterfaceClassInfo = targetMethod.declaringClass();\n        String generatedClassName = getGeneratedClassName(targetMethod);\n        final MethodInfo target = targetMethod;\n        gizmo.class_(generatedClassName, cc -> {\n            cc.implements_(GenericType.ofClass(ResteasyReactiveContextResolver.class,\n                    TypeArgument.of(returnTypeClassName)));\n            cc.defaultConstructor();\n            cc.method(\"getContext\", mc -> {\n                mc.returning(Object.class);\n                ParamVar typeParam = mc.parameter(\"type\", Class.class);\n                mc.body(bc -> {\n                    LinkedHashMap<String, Expr> targetMethodParams = new LinkedHashMap<>();\n                    for (Type paramType : target.parameterTypes()) {","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest-client/deployment/src/main/java/io/quarkus/rest/client/reactive/deployment/ClientContextResolverHandler.java#L81-L117","documentation":"@RegisterClientContextResolver annotates a static method inside a REST client interface that supplies custom context resolvers. Quarkus generates the wiring at build time and requires the annotated method's return type to be assignable to the resolver type expected by the annotated parameter. This IllegalStateException fires when the method returns a type incompatible with the expected resolver return type.","triggerScenarios":"Annotating a static method in a REST client interface whose return type is not assignable to the expected return type (declared via the annotation target/parameter); e.g. the method returns String while a Response-based context resolver is expected.","commonSituations":"Copy-pasting a context resolver method from another client; changing the resolver type but forgetting to change the method return type; using a non-static or wrong-signature helper method.","solutions":["Make the annotated static method return exactly the type expected (assignable to the expected return type shown in the message)","Ensure the method is static and declared inside the REST client interface","If you intended a different resolver kind, use the matching annotation/target type for your return type","Check the generated message for '${className}#${methodName}' to locate the offending method quickly"],"exampleFix":"// before\n@RegisterClientContextResolver\nstatic String myResolver() { return \"x\"; } // wrong return type\n// after\n@RegisterClientContextResolver\nstatic MyContextType myResolver() { return new MyContextType(); }","handlingStrategy":"validation","validationCode":"// Pre-check before build-time processing (conceptual):\n// static method, return type assignable to expected resolver type\nstatic void validate(MethodInfo m, DotName expected) {\n    if (!TypeKind.isAssignableFrom(expected, m.returnType().name()))\n        throw new IllegalStateException(m.name() + \" must return \" + expected);\n}","typeGuard":null,"tryCatchPattern":"try {\n    classResult.process();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"RegisterClientContextResolver\")) {\n        // point developer at className#methodName in message\n    }\n    throw e;\n}","preventionTips":["Keep @RegisterClientContextResolver methods static and returning the expected resolver type","Read the generated message — it names the exact offending class#method","Align return types when changing resolver target types","Add an early build-step validation of annotated methods in large codebases"],"tags":["rest-client","annotation-processing","build-time","illegal-state"],"backgroundTag":"rest-client-annotation-misuse","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"}