{"record":{"id":"dada4eafc344c8ba","repo":"quarkusio/quarkus","slug":"failed-to-instantiate-the-client-headers-factory","errorCode":null,"errorMessage":"Failed to instantiate the client headers factory ${class}. Make sure the bean is properly configured for CDI injection.","messagePattern":"Failed to instantiate the client headers factory (.+?)\\. Make sure the bean is properly configured for CDI injection\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/QuarkusRestClientBuilderImpl.java","lineNumber":221,"sourceCode":"    }\n\n    @Override\n    public QuarkusRestClientBuilder register(Object component, Class<?>... contracts) {\n        delegate.register(component, contracts);\n        return this;\n    }\n\n    @Override\n    public QuarkusRestClientBuilder register(Object component, Map<Class<?>, Integer> contracts) {\n        delegate.register(component, contracts);\n        return this;\n    }\n\n    @Override\n    public QuarkusRestClientBuilder clientHeadersFactory(Class<? extends ClientHeadersFactory> clientHeadersFactoryClass) {\n        ClientHeadersFactory bean = BeanGrabber.getBeanIfDefined(clientHeadersFactoryClass);\n        if (bean == null) {\n            throw new IllegalArgumentException(\"Failed to instantiate the client headers factory \" + clientHeadersFactoryClass\n                    + \". Make sure the bean is properly configured for CDI injection.\");\n        }\n\n        return clientHeadersFactory(bean);\n    }\n\n    @Override\n    public QuarkusRestClientBuilder clientHeadersFactory(ClientHeadersFactory clientHeadersFactory) {\n        delegate.register(new ClientHeadersFactoryContextResolver(clientHeadersFactory));\n        return this;\n    }\n\n    @Override\n    public QuarkusRestClientBuilder httpClientOptions(Class<? extends HttpClientOptions> httpClientOptionsClass) {\n        delegate.httpClientOptions(httpClientOptionsClass);\n        return this;\n    }\n","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/QuarkusRestClientBuilderImpl.java#L203-L239","documentation":"QuarkusRestClientBuilder.clientHeadersFactory(Class) resolves the given class as a CDI bean via BeanGrabber. If no bean of that type is defined in the CDI container (bean == null), the builder throws IllegalArgumentException asking to configure the bean properly. Programmatic client builders require the factory to be a managed CDI bean rather than just a class on the classpath.","triggerScenarios":"Calling builder.clientHeadersFactory(MyFactory.class) where MyFactory lacks a bean-defining annotation (@ApplicationScoped/@Dependent etc.), lacks a beans.xml in the archive, or was excluded by CDI discovery rules in native/tests.","commonSituations":"Plain class without a scope annotation used as the factory; bean inside a library JAR without beans.xml or annotations; tests/native where unused beans were removed by CDI pruning; using @RegisterRestClient config-based clients where the programmatic builder is bypassed.","solutions":["Annotate the factory class with @ApplicationScoped (or @Dependent) so CDI discovers it","Ensure the containing archive has bean discovery enabled (beans.xml with bean-discovery-mode=annotated or annotation presence)","Register the factory via config instead: quarkus.rest-client.<name>.headers-baggage / use @ClientHeadersFactory on an injected factory per the MP Rest Client spec"],"exampleFix":"// before\npublic class MyHeadersFactory implements ClientHeadersFactory { ... }\n// after\n@ApplicationScoped\npublic class MyHeadersFactory implements ClientHeadersFactory { ... }","handlingStrategy":"validation","validationCode":"MyHeadersFactory probe = BeanGrabber.getBeanIfDefined(MyHeadersFactory.class);\nif (probe == null) {\n    throw new IllegalStateException(\"MyHeadersFactory is not a CDI bean; add @ApplicationScoped and ensure bean discovery\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    builder.clientHeadersFactory(MyHeadersFactory.class);\n} catch (IllegalArgumentException e) {\n    builder.clientHeadersFactory(new MyHeadersFactory()); // fallback to manual instance if API allows\n}","preventionTips":["Annotate every ClientHeadersFactory with a bean-defining scope","Ensure libraries containing factories have bean-discovery enabled (annotations or beans.xml)","In tests/native, verify the factory is actually referenced so CDI pruning keeps it"],"tags":["rest-client","cdi","bean-resolution"],"backgroundTag":"cdi-bean-not-found","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"}