quarkusio/quarkus · error · IllegalArgumentException

Unable to determine the proper baseUrl/baseUri. Consider…

Error message

Unable to determine the proper baseUrl/baseUri. Consider registering using @RegisterRestClient(baseUri="someuri"), @RegisterRestClient(configKey="orkey"), or by adding '%s' or '%s' to your Quarkus configuration

What it means

Thrown by RestClientCDIDelegateBuilder.configureBaseUrl when neither an @RegisterRestClient(baseUri=...) annotation nor a quarkus.rest-client.<key>.url/uri (or config-key scoped, or MP mp.rest-client url/uri) property provides a base URL for the client. The MicroProfile Rest Client spec requires a base URI to build requests, so Quarkus aborts client creation with guidance on all supported ways to supply one.

Solutions

Add the URL to configuration using the exact key shown in the error message: quarkus.rest-client.<propertyPrefix>.url=http://host:port (or .uri)
Or set it in code/annotation: @RegisterRestClient(baseUri = "http://localhost:8080") on the interface
If using configKey, ensure the property prefix matches the configKey exactly, not the interface FQN
Check the active profile (e.g. %prod, %dev) isn't overriding/clearing the property; the error prints the two exact expected key formats — copy them

Example fix

// before
@RegisterRestClient
public interface MyServiceClient { ... }
// after
@RegisterRestClient(baseUri = "http://localhost:8080")
public interface MyServiceClient { ... }
// or in application.properties:
// quarkus.rest-client.MyServiceClient.url=http://localhost:8080

Defensive patterns

Strategy: validation

Validate before calling

String key = "quarkus.rest-client." + (configKey != null ? configKey : MyClient.class.getName());
var cfg = org.eclipse.microprofile.config.ConfigProvider.getConfig();
if (cfg.getOptionalValue(key + ".url", String.class).isEmpty()
    && cfg.getOptionalValue(key + ".uri", String.class).isEmpty()) {
    throw new IllegalStateException("No base URL configured for rest client; set " + key + ".url");
}

Try / catch

try {
    MyClient client = Arc.container().instance(MyClient.class).get();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unable to determine the proper baseUrl/baseUri")) {
        throw new ConfigurationException("Set the base URL; expected keys are shown in: " + e.getMessage(), e);
    }
    throw e;
}

Prevention

Always set baseUri on @RegisterRestClient or a quarkus.rest-client.<key>.url property when creating a client interface
Copy the exact property key formats from the error message
Verify config per profile (%dev/%prod) in dev mode config editor
Keep configKey on the annotation consistent with the property prefix

When it happens

Trigger: CDI injection of a @RegisterRestClient interface whose annotation has no baseUri/baseUrl, and no quarkus.rest-client.<name>.url / .uri property exists under the interface FQN or the registered configKey; configureBuilder -> configureBaseUrl finds propertyOptional empty and baseUriFromAnnotation empty/null.

Common situations: Forgot to add the URL to application.properties after creating the interface; property key uses the wrong prefix (config key mismatch — property defined under a key that doesn't match @RegisterRestClient(configKey=...) or the interface FQN); dev services/profile-specific config overriding the property in the active profile; typo like 'quarkus.rest-client.my-service.url' vs actual key 'myservice'.

Related errors

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

Appendix: source

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

    private void configureTimeouts(QuarkusRestClientBuilder builder) {
        Long connectTimeout = restClientConfig.connectTimeout().orElse(this.configRoot.connectTimeout());
        if (connectTimeout != null) {
            builder.connectTimeout(connectTimeout, TimeUnit.MILLISECONDS);
        }

        Long readTimeout = restClientConfig.readTimeout().orElse(this.configRoot.readTimeout());
        if (readTimeout != null) {
            builder.readTimeout(readTimeout, TimeUnit.MILLISECONDS);
        }
    }

    private void configureBaseUrl(QuarkusRestClientBuilder builder) {
        Optional<String> propertyOptional = oneOf(restClientConfig.uriReload(), restClientConfig.urlReload());
        if (((baseUriFromAnnotation == null) || baseUriFromAnnotation.isEmpty())
                && propertyOptional.isEmpty()) {
            String propertyPrefix = configKey != null ? configKey : "\"" + jaxrsInterface.getName() + "\"";
            throw new IllegalArgumentException(
                    String.format(
                            "Unable to determine the proper baseUrl/baseUri. " +
                                    "Consider registering using @RegisterRestClient(baseUri=\"someuri\"), @RegisterRestClient(configKey=\"orkey\"), "
                                    +
                                    "or by adding '%s' or '%s' to your Quarkus configuration",
                            String.format(REST_URL_FORMAT, propertyPrefix), String.format(REST_URI_FORMAT, propertyPrefix)));
        }
        String baseUrl = propertyOptional.orElse(baseUriFromAnnotation);

        try {
            builder.baseUri(new URI(baseUrl));
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("The value of URL was invalid " + baseUrl, e);
        }
    }

    private void configureDomainSocket(QuarkusRestClientBuilder builder) {
        restClientConfig.domainSocket().ifPresent(builder::domainSocket);

View on GitHub (pinned to e1c734241f)