quarkusio/quarkus · error · IllegalArgumentException

proxyHost must not be null

Error message

proxyHost must not be null

What it means

Thrown by QuarkusRestClientBuilder.proxyAddress when the host argument is null. The MicroProfile REST client builder API requires a non-null host to configure an HTTP proxy, so a null is rejected immediately with IllegalArgumentException.

Source

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

    }

    @Override
    public RestClientBuilder queryParamStyle(QueryParamStyle queryParamStyle) {
        this.queryParamStyle = queryParamStyle;
        return this;
    }

    @Override
    public RestClientBuilder header(final String name, final Object value) {
        headers.add(Objects.requireNonNull(name, "A header name is required."),
                Objects.requireNonNull(value, "Value for header is required."));
        return this;
    }

    @Override
    public RestClientBuilder proxyAddress(String host, int port) {
        if (host == null) {
            throw new IllegalArgumentException("proxyHost must not be null");
        }
        if (port <= 0 || port > 65535) {
            throw new IllegalArgumentException("Invalid port number");
        }
        this.proxyHost = host;
        this.proxyPort = port;
        return this;
    }

    @Override
    public RestClientBuilder baseUrl(URL url) {
        try {
            baseURI = url.toURI();
            return this;
        } catch (URISyntaxException e) {
            throw new RuntimeException(e.getMessage());
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a valid non-null hostname string to proxyAddress
2. Verify the proxy host config property (quarkus.rest-client.<config-key>.proxy-address="host:port") is set and well-formed
3. Ensure the environment variable or system property supplying the proxy host is actually defined in the deployment environment

Example fix

// before
String host = System.getenv("PROXY_HOST");
builder.proxyAddress(host, 8080); // NPE-ish: IllegalArgumentException proxyHost must not be null
// after
String host = System.getenv("PROXY_HOST");
if (host != null) {
    builder.proxyAddress(host, 8080);
}

Objects.requireNonNull(proxyHost, "proxyHost must not be null");
if (proxyPort <= 0 || proxyPort > 65535) throw new IllegalArgumentException("Invalid port number");

try {
    builder.proxyAddress(host, port);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("proxyHost must not be null")) {
        log.warn("Proxy host not configured; skipping proxy setup");
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling builder.proxyAddress(null, port) directly; calling configureProxy programmatically from config where quarkus.rest-client.<key>.proxy-address host part is missing or parsed to null.

Common situations: Reading proxy host from an environment variable that is unset; misconfigured quarkus.rest-client proxy properties where only the port was given; placeholder not resolved in properties files.

Related errors

• Invalid port number
• Invalid proxy string. Expected <hostname>:<port>, found '${p
• Invalid proxy setting. The port is not a number in '${proxy}
• Unknown JAR package type '${value}'
• Unable to resolve locale: ${value}

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