quarkusio/quarkus · error · IllegalStateException

The Reactive REST Client needs to be built within the contex

Error message

The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC (CDI) context running.

What it means

RestClientBuilderImpl.build(Class) requires the ArC CDI container because it reads config mappings (RestClientsConfig) and CDI-registered providers during build. If Arc.container() returns null — meaning no initialized ArC container — build throws this IllegalStateException. Quarkus rest clients may only be built inside a running Quarkus application.

Source

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

    @Override
    public RestClientBuilderImpl queryParamStyle(final QueryParamStyle style) {
        queryParamStyle = style;
        return this;
    }

    @Override
    public RestClientBuilder header(final String name, final Object value) {
        headers.add(Objects.requireNonNull(name, "A header name is required."),
                Objects.requireNonNull(value, "Value for header is required."));
        return this;
    }

    @Override
    public <T> T build(Class<T> aClass) throws IllegalStateException, RestClientDefinitionException {
        ArcContainer arcContainer = Arc.container();
        if (arcContainer == null) {
            throw new IllegalStateException(
                    "The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC (CDI) context running.");
        }

        SmallRyeConfig config = ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);
        RestClientsConfig restClients = config.getConfigMapping(RestClientsConfig.class);

        // support overriding the URI from the override-uri property
        var overrideUrlKeyName = String.format("quarkus.rest-client.\"%s\".override-uri", aClass.getName());
        Optional<String> maybeOverrideUri = config.getOptionalValue(overrideUrlKeyName, String.class);
        if (maybeOverrideUri.isPresent()) {
            uri = URI.create(maybeOverrideUri.get());
        }

        if (uri == null) {
            // mandated by the spec
            throw new IllegalStateException("No URL specified. Cannot build a rest client without URL");
        }

View on GitHub (pinned to e1c734241f)

Solutions

1. Run inside a Quarkus application (start Quarkus or use @QuarkusTest) before building the client.
2. In tests, inject the client (@RestClient MyClient) or use QuarkusRestClientBuilder only under @QuarkusTest.
3. If you truly need a client outside CDI, use the plain MP/SmallRye RestClientBuilder instead of the Quarkus-specific one.

Example fix

// before
class MyTest {
    MyClient c = QuarkusRestClientBuilder.newBuilder().baseUri(uri).build(MyClient.class); // IllegalStateException
}

// after
@QuarkusTest
class MyTest {
    @RestClient MyClient c; // built by Quarkus inside the ArC context
}

if (io.quarkus.arc.Arc.container() == null) { throw new IllegalStateException("Start the Quarkus application before building rest clients"); }

boolean quarkusRunning() { return io.quarkus.arc.Arc.container() != null
        && io.quarkus.arc.Arc.container().beanManager() != null; }

try {
    T client = builder.build(MyClient.class);
} catch (IllegalStateException e) {
    // not inside a Quarkus/ArC context — construct client outside Quarkus API or start Quarkus
}

When it happens

Trigger: Calling QuarkusRestClientBuilder.build(...) in a plain JVM unit test without @QuarkusTest, in a main() method before Quarkus starts, or from native-image code executed outside the Quarkus runtime.

Common situations: Plain JUnit tests that build the client directly without the Quarkus test framework; building clients in a shutdown hook or static initializer after the container shut down; using the Quarkus builder class in a non-Quarkus application.

Related errors

• Not possible to define the scope %s for the REST client %s
• RestClientProxy is closed
• Failed to instantiate the HTTP client options " + httpClient
• Multiple @PostConstruct interceptor methods declared on clas
• Multiple @PreDestroy interceptor methods declared on class:

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