quarkusio/quarkus · error · IllegalArgumentException

Unable to determine the proper baseUrl/baseUri. Consider reg

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.

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)

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.