quarkusio/quarkus · error · IllegalArgumentException

Failed to instantiate the HTTP client options " + httpClient

Error message

Failed to instantiate the HTTP client options " + httpClientOptionsClass + ". Make sure the bean is properly configured for CDI injection.

What it means

RestClientBuilderImpl.httpClientOptions(Class) resolves an HttpClientOptions instance from the CDI container via BeanGrabber.getBeanIfDefined. When the container has no bean for that class, it throws this IllegalArgumentException. Quarkus only injects beans that are discoverable CDI beans (e.g. annotated @ApplicationScoped or registered via @Unremovable), so an unmanaged or removed class cannot be resolved.

Source

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

        this.disableDefaultMapper = disableDefaultMapper;
        return this;
    }

    public RestClientBuilderImpl enableCompression(boolean enableCompression) {
        this.enableCompression = enableCompression;
        return this;
    }

    public RestClientBuilderImpl domainSocket(String path) {
        this.domainSocketPath = path;
        return this;
    }

    @Override
    public RestClientBuilderImpl httpClientOptions(Class<? extends HttpClientOptions> httpClientOptionsClass) {
        HttpClientOptions bean = BeanGrabber.getBeanIfDefined(httpClientOptionsClass);
        if (bean == null) {
            throw new IllegalArgumentException("Failed to instantiate the HTTP client options " + httpClientOptionsClass
                    + ". Make sure the bean is properly configured for CDI injection.");
        }

        return httpClientOptions(bean);
    }

    @Override
    public RestClientBuilderImpl httpClientOptions(HttpClientOptions httpClientOptions) {
        register(new HttpClientOptionsContextResolver(httpClientOptions));
        return this;
    }

    public RestClientBuilderImpl clientOptionsCustomizer(Consumer<HttpClientOptions> clientOptionsCustomizer) {
        clientBuilder.clientOptionsCustomizer(clientOptionsCustomizer);
        return this;
    }

    @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Annotate the HttpClientOptions implementation with a bean-defining annotation such as @ApplicationScoped (and import io.vertx.axle/core HttpClientOptions class you intend).
2. If ArC removes the bean as unused, annotate it with @io.quarkus.arc.Unremovable.
3. Register the bean programmatically if it cannot carry annotations (e.g. via an @ApplicationRoot-scoped producing @Produces method).
4. Alternatively pass an already-constructed HttpClientOptions instance using the httpClientOptions(HttpClientOptions instance) overload instead of the class-based one.

Example fix

// before
public class MyHttpClientOptions extends HttpClientOptions { ... }
builder.httpClientOptions(MyHttpClientOptions.class); // IllegalArgumentException

// after
@ApplicationScoped
@Unremovable
public class MyHttpClientOptions extends HttpClientOptions { ... }
builder.httpClientOptions(MyHttpClientOptions.class); // resolves via CDI

HttpClientOptions opts = BeanGrabber.getBeanIfDefined(MyHttpClientOptions.class); // or check with Arc.container().instance(MyHttpClientOptions.class).isAvailable() before calling builder.httpClientOptions(MyHttpClientOptions.class)

boolean isCdiBean(Class<?> c) { return java.util.Optional.ofNullable(io.quarkus.arc.Arc.container())
        .map(a -> a.instance(c).isAvailable()).orElse(false); }

try {
    builder.httpClientOptions(MyOptions.class);
} catch (IllegalArgumentException e) {
    // fall back to default options or instance overload
    builder.httpClientOptions(new MyOptions());
}

When it happens

Trigger: Calling QuarkusRestClientBuilder.httpClientOptions(SomeHttpClientOptions.class) where SomeHttpClientOptions has no CDI bean definition, or the bean exists but was removed as unused during build-time augmentation.

Common situations: Passing a plain class (no bean-defining annotation) as the options class; the options class being in a package excluded from bean discovery; ArC removing the bean as @Unremovable-less unused bean; running outside a Quarkus runtime where CDI is absent.

Related errors

• Unable to find the GrpcClientConfigProvider
• Unable to retrieve the gRPC Channel ${name}
• Token exchange is required but OIDC client is configured to
• Quartz scheduler is either explicitly disabled through quark
• Unable to find redis host provider identified with " + name

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