What causes "The value of URL was invalid " + baseUrl" in quarkusio/quarkus?

Print/inspect the resolved value (quarkus rest-client config at startup or dev mode config editor) and fix the syntax: ensure scheme://host[:port][/path] with proper encoding

quarkusio/quarkus · error · IllegalArgumentException

The value of URL was invalid " + baseUrl

Error message

The value of URL was invalid " + baseUrl

What it means

Thrown by RestClientCDIDelegateBuilder.configureBaseUrl when the resolved base URL (from configuration or the annotation) is not a syntactically valid URI: new URI(baseUrl) throws URISyntaxException, which Quarkus wraps in an IllegalArgumentException including the offending value. The client cannot be constructed with an unparseable base URI.

Source

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

    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);
    }

    private void configureClientOptionsCustomizer(QuarkusRestClientBuilder builder) {
        builder.httpClientOptionsCustomizer(new Consumer<>() {
            @Override
            public void accept(HttpClientOptions httpClientOptions) {
                String metricsName = httpClientOptions.getMetricsName();
                if (metricsName == null || metricsName.isEmpty()) {
                    httpClientOptions.setMetricsName("rest-client|" + configKey);
                }
            }
        });
    }

View on GitHub (pinned to e1c734241f)

Solutions

Print/inspect the resolved value (quarkus rest-client config at startup or dev mode config editor) and fix the syntax: ensure scheme://host[:port][/path] with proper encoding
Encode or escape special characters (spaces -> %20), wrap IPv6 hosts in brackets, or URL-encode path segments
Fix unresolved property placeholders — verify the referenced config property actually exists and is expanded at runtime
Validate locally with new URI(value) in a test or jshell to pinpoint the offending character
If the value comes from an env var, check it is actually set and correctly formatted in the deployment environment

Example fix

// before (application.properties)
quarkus.rest-client.myservice.url=http://${unresolved.host}:8080/api v1
// after
quarkus.rest-client.myservice.url=http://services.internal:8080/api%20v1

Defensive patterns

Strategy: validation

Validate before calling

String url = org.eclipse.microprofile.config.ConfigProvider.getConfig()
    .getValue("quarkus.rest-client.myservice.url", String.class);
try {
    new java.net.URI(url);
} catch (java.net.URISyntaxException e) {
    throw new IllegalStateException("Configured rest-client URL is not a valid URI: " + url, e);
}

Try / catch

try {
    MyClient client = Arc.container().instance(MyClient.class).get();
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("The value of URL was invalid")) {
        throw new ConfigurationException("Fix the base URL syntax: " + e.getMessage(), e);
    }
    throw e;
}

Prevention

Validate URL config values with new URI(...) in a startup test
Avoid unencoded spaces/special characters in configured URLs; URL-encode paths
Ensure config placeholders (${...}) reference existing properties so they resolve before use
Standardize on scheme://host:port/path format in all environments

When it happens

Trigger: quarkus.rest-client.<key>.url or .uri (or @RegisterRestClient(baseUri=...)) contains a value that fails URI parsing — e.g. missing scheme, illegal characters (unescaped spaces, '{', '|', non-ASCII), or a malformed string like 'http:/host' or leftover property placeholder '${HOST}' that was not resolved.

Common situations: SmallRye config property substitution failed and the literal '${services.host}' was passed through; URL copied with a trailing space or contains unescaped space in path; scheme typo like 'htp://'; IPv6 host without brackets; environment-specific value empty after expansion leaving 'http://:8080'.

Related errors

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