What causes "Failed to convert REST client URL to URI" in quarkusio/quarkus?

Fix or sanitize the URL string before constructing it (encode spaces, add scheme)

quarkusio/quarkus · error · IllegalArgumentException

Failed to convert REST client URL to URI

Error message

Failed to convert REST client URL to URI

What it means

RestClientBuilderImpl.baseUrl(URL) converts the java.net.URL to a java.net.URI to store internally. URL.toURI() throws URISyntaxException when the URL is not a valid URI (illegal characters, spaces, missing scheme, etc.); the builder wraps it in this IllegalArgumentException. Underlying MP Rest Client requires an absolute, syntactically valid base URI.

Source

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

    private ClientLogger clientLogger;
    private LoggingScope loggingScope;
    private Integer loggingBodyLimit;
    private Set<String> maskedHeaders;

    private Boolean trustAll;
    private String userAgent;
    private Boolean disableDefaultMapper;
    private Boolean enableCompression;
    private String domainSocketPath;
    private Consumer<HttpClientOptions> clientOptionsCustomizer;

    @Override
    public RestClientBuilderImpl baseUrl(URL url) {
        try {
            this.uri = url.toURI();
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Failed to convert REST client URL to URI", e);
        }
        return this;
    }

    @Override
    public RestClientBuilderImpl connectTimeout(long timeout, TimeUnit timeUnit) {
        clientBuilder.connectTimeout(timeout, timeUnit);
        return this;
    }

    @Override
    public RestClientBuilderImpl readTimeout(long timeout, TimeUnit timeUnit) {
        clientBuilder.readTimeout(timeout, timeUnit);
        return this;
    }

    public RestClientBuilderImpl tlsConfiguration(TlsConfiguration tlsConfiguration) {
        clientBuilder.tlsConfig(new TlsConfig() {

View on GitHub (pinned to e1c734241f)

Solutions

Fix or sanitize the URL string before constructing it (encode spaces, add scheme)
Use builder.baseUri(URI.create(...)) and validate the URI up front
Trim/truncate the config value — often a trailing newline/space or truncated env var causes the syntax error

Example fix

// before
builder.baseUrl(new URL(configUrl.trim()));
// after
URI uri = URI.create(configUrl.trim());
if (!uri.isAbsolute()) throw new IllegalArgumentException("URL must be absolute: " + configUrl);
builder.baseUri(uri);

Defensive patterns

Strategy: validation

Validate before calling

static URI toSafeUri(String raw) {
    String cleaned = raw == null ? "" : raw.trim().replace(" ", "%20");
    URI uri = URI.create(cleaned);
    if (!uri.isAbsolute()) throw new IllegalArgumentException("Base URL must be absolute: " + raw);
    return uri;
}

Type guard

static boolean isAbsoluteHttpUrl(String s) {
    try { URI u = new URI(s.trim()); return ("http".equalsIgnoreCase(u.getScheme()) || "https".equalsIgnoreCase(u.getScheme())) && u.getHost() != null; }
    catch (URISyntaxException e) { return false; }
}

Try / catch

try {
    builder.baseUrl(new URL(rawUrl));
} catch (IllegalArgumentException e) {
    throw new ConfigurationException("Invalid base URL: " + rawUrl, e);
}

Prevention

Trim and URL-encode config-derived base URLs before use
Prefer baseUri(URI.create(...)) so failures surface at URI.create time with clearer messages
Never build base URLs by naive string concatenation; validate scheme and host presence

When it happens

Trigger: Calling builder.baseUrl(new URL(...)) with a URL containing spaces or other illegal characters, a relative URL, or one whose scheme/authority is malformed so URL.toURI() fails.

Common situations: Base URL read from config with an unencoded space or query string; URL constructed by string concatenation with typos (missing scheme like 'example.com/api'); non-ASCII hostnames not IDN-encoded.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

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