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 '${quarkus.config.rest.url.format}' or '${quarkus.config.rest.uri.format}' to your Quarkus configuration

What it means

configureBaseUrl() refuses to build the client when it cannot determine the target URL: neither @RegisterRestClient(baseUri/url) nor any config property supplied one. Quarkus requires an explicit base URI/URL for every MicroProfile REST client and fails fast with guidance listing the exact property name expected for the configKey or interface name.

Source

Thrown at extensions/resteasy-classic/resteasy-client/runtime/src/main/java/io/quarkus/restclient/runtime/RestClientBase.java:286

    }

    protected void configureTimeouts(RestClientBuilder 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);
        }
    }

    protected void configureBaseUrl(RestClientBuilder builder) {
        Optional<String> baseUrlOptional = oneOf(restClientConfig.uriReload(), restClientConfig.urlReload());
        if (((baseUriFromAnnotation == null) || baseUriFromAnnotation.isEmpty()) && baseUrlOptional.isEmpty()) {
            String propertyPrefix = configKey != null ? configKey : proxyType.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(QUARKUS_CONFIG_REST_URL_FORMAT, propertyPrefix),
                            String.format(QUARKUS_CONFIG_REST_URI_FORMAT, propertyPrefix)));
        }
        String baseUrl = baseUrlOptional.orElse(baseUriFromAnnotation);

        try {
            builder.baseUrl(new URL(baseUrl));
        } catch (MalformedURLException e) {
            if (e.getMessage().contains(
                    "It must be enabled by adding the --enable-url-protocols=https option to the native-image command")) {
                throw new IllegalArgumentException(baseUrl
                        + " requires SSL support but it is disabled. You probably have set quarkus.ssl.native to false.");
            }

View on GitHub (pinned to e1c734241f)

Solutions

Add quarkus.rest-client.<key>.url=https://host (where <key> is the configKey or FQCN of the interface)
Or set baseUri on the annotation: @RegisterRestClient(baseUri = "https://api.example.com")
Check the active profile — put the property in application.properties, not just application-<inactive-profile>.properties
Verify env var mapping in containers and ensure no profile qualifier suppresses the property

Example fix

// before (application.properties)
# quarkus.rest-client.weather-client.url missing
// after
// @RegisterRestClient(configKey = "weather-client")
quarkus.rest-client.weather-client.url=https://api.weather.example.com

Defensive patterns

Strategy: validation

Validate before calling

// assert a base URL is resolvable for each client before use
Config cfg = ConfigProvider.getConfig();
String url = cfg.getOptionalValue("quarkus.rest-client.my-client.url", String.class)
    .or(() -> cfg.getOptionalValue("my-client/mp-rest/url", String.class))
    .orElseThrow(() -> new IllegalStateException("No base URL configured for my-client"));

Prevention

Set @RegisterRestClient(baseUri=...) as a safe default and override via config per environment
Standardize one config-key naming convention across projects
Include client URL properties in deployment config templates for every profile
Add a startup health check that resolves all client URLs

When it happens

Trigger: The interface has no baseUri in @RegisterRestClient and no quarkus.rest-client.<key>.url / .uri (or <configKey>.url/.uri, or the MP-style <FQCN>/mp-rest/url) property is set for either the proxy type name or the configKey.

Common situations: Property written under the wrong prefix (interface name changed, configKey typo); property defined only in an inactive profile (e.g. %prod); env-var mapping mismatch (QUARKUS_REST_CLIENT_<KEY>_URL not resolvable); @RegisterRestClient configKey set but config uses the plain class name.

Related errors

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