{"record":{"id":"b64b60600aa8bd65","repo":"quarkusio/quarkus","slug":"the-reactive-rest-client-needs-to-be-built-within","errorCode":null,"errorMessage":"The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC (CDI) context running.","messagePattern":"The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC \\(CDI\\) context running\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/RestClientBuilderImpl.java","lineNumber":502,"sourceCode":"\n    @Override\n    public RestClientBuilderImpl queryParamStyle(final QueryParamStyle style) {\n        queryParamStyle = style;\n        return this;\n    }\n\n    @Override\n    public RestClientBuilder header(final String name, final Object value) {\n        headers.add(Objects.requireNonNull(name, \"A header name is required.\"),\n                Objects.requireNonNull(value, \"Value for header is required.\"));\n        return this;\n    }\n\n    @Override\n    public <T> T build(Class<T> aClass) throws IllegalStateException, RestClientDefinitionException {\n        ArcContainer arcContainer = Arc.container();\n        if (arcContainer == null) {\n            throw new IllegalStateException(\n                    \"The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC (CDI) context running.\");\n        }\n\n        SmallRyeConfig config = ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);\n        RestClientsConfig restClients = config.getConfigMapping(RestClientsConfig.class);\n\n        // support overriding the URI from the override-uri property\n        var overrideUrlKeyName = String.format(\"quarkus.rest-client.\\\"%s\\\".override-uri\", aClass.getName());\n        Optional<String> maybeOverrideUri = config.getOptionalValue(overrideUrlKeyName, String.class);\n        if (maybeOverrideUri.isPresent()) {\n            uri = URI.create(maybeOverrideUri.get());\n        }\n\n        if (uri == null) {\n            // mandated by the spec\n            throw new IllegalStateException(\"No URL specified. Cannot build a rest client without URL\");\n        }\n","sourceCodeStart":484,"sourceCodeEnd":520,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/RestClientBuilderImpl.java#L484-L520","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run inside a Quarkus application (start Quarkus or use @QuarkusTest) before building the client.","In tests, inject the client (@RestClient MyClient) or use QuarkusRestClientBuilder only under @QuarkusTest.","If you truly need a client outside CDI, use the plain MP/SmallRye RestClientBuilder instead of the Quarkus-specific one."],"exampleFix":"// before\nclass MyTest {\n    MyClient c = QuarkusRestClientBuilder.newBuilder().baseUri(uri).build(MyClient.class); // IllegalStateException\n}\n\n// after\n@QuarkusTest\nclass MyTest {\n    @RestClient MyClient c; // built by Quarkus inside the ArC context\n}","handlingStrategy":"type-guard","validationCode":"if (io.quarkus.arc.Arc.container() == null) { throw new IllegalStateException(\"Start the Quarkus application before building rest clients\"); }","typeGuard":"boolean quarkusRunning() { return io.quarkus.arc.Arc.container() != null\n        && io.quarkus.arc.Arc.container().beanManager() != null; }","tryCatchPattern":"try {\n    T client = builder.build(MyClient.class);\n} catch (IllegalStateException e) {\n    // not inside a Quarkus/ArC context — construct client outside Quarkus API or start Quarkus\n}","preventionTips":["Only build Quarkus rest clients under @QuarkusTest or a running Quarkus app.","Prefer @Inject @RestClient over manual builder usage in CDI code.","Avoid building clients in static initializers or shutdown hooks."],"tags":["cdi","quarkus","rest-client","lifecycle"],"backgroundTag":"cdi-container-not-running","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}