quarkusio/quarkus · error · IllegalArgumentException

Failed to instantiate the client headers factory ${class}. M

Error message

Failed to instantiate the client headers factory ${class}. Make sure the bean is properly configured for CDI injection.

What it means

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.

Source

Thrown at extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/QuarkusRestClientBuilderImpl.java:221

    }

    @Override
    public QuarkusRestClientBuilder register(Object component, Class<?>... contracts) {
        delegate.register(component, contracts);
        return this;
    }

    @Override
    public QuarkusRestClientBuilder register(Object component, Map<Class<?>, Integer> contracts) {
        delegate.register(component, contracts);
        return this;
    }

    @Override
    public QuarkusRestClientBuilder clientHeadersFactory(Class<? extends ClientHeadersFactory> clientHeadersFactoryClass) {
        ClientHeadersFactory bean = BeanGrabber.getBeanIfDefined(clientHeadersFactoryClass);
        if (bean == null) {
            throw new IllegalArgumentException("Failed to instantiate the client headers factory " + clientHeadersFactoryClass
                    + ". Make sure the bean is properly configured for CDI injection.");
        }

        return clientHeadersFactory(bean);
    }

    @Override
    public QuarkusRestClientBuilder clientHeadersFactory(ClientHeadersFactory clientHeadersFactory) {
        delegate.register(new ClientHeadersFactoryContextResolver(clientHeadersFactory));
        return this;
    }

    @Override
    public QuarkusRestClientBuilder httpClientOptions(Class<? extends HttpClientOptions> httpClientOptionsClass) {
        delegate.httpClientOptions(httpClientOptionsClass);
        return this;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Annotate the factory class with @ApplicationScoped (or @Dependent) so CDI discovers it
2. Ensure the containing archive has bean discovery enabled (beans.xml with bean-discovery-mode=annotated or annotation presence)
3. Register the factory via config instead: quarkus.rest-client.<name>.headers-baggage / use @ClientHeadersFactory on an injected factory per the MP Rest Client spec

Example fix

// before
public class MyHeadersFactory implements ClientHeadersFactory { ... }
// after
@ApplicationScoped
public class MyHeadersFactory implements ClientHeadersFactory { ... }

MyHeadersFactory probe = BeanGrabber.getBeanIfDefined(MyHeadersFactory.class);
if (probe == null) {
    throw new IllegalStateException("MyHeadersFactory is not a CDI bean; add @ApplicationScoped and ensure bean discovery");
}

try {
    builder.clientHeadersFactory(MyHeadersFactory.class);
} catch (IllegalArgumentException e) {
    builder.clientHeadersFactory(new MyHeadersFactory()); // fallback to manual instance if API allows
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Not possible to define the scope %s for the REST client %s
• Failed to instantiate the HTTP client options " + httpClient
• The Reactive REST Client needs to be built within the contex
• Multiple beans match the type:
• Injectable beans are not supported in client

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