apache/flink · error · IllegalArgumentException

The given host:port ('{}') doesn't contain a valid host

Error message

The given host:port ('{}') doesn't contain a valid host

What it means

NetUtils.validateHostPortString parses a 'host:port' string by constructing a java.net.URL (prefixing 'http://' if no scheme is present) and rejects it when the resulting URL has a null host. It is the strict validation behind Flink APIs that accept a single host:port string. The message echoes the offending input so the misconfigured value is visible in the log.

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/NetUtils.java:116

     * <p>Works also for ipv6.
     *
     * <p>See:
     * http://stackoverflow.com/questions/2345063/java-common-way-to-validate-and-convert-hostport-to-inetsocketaddress
     *
     * @return URL object for accessing host and port
     */
    private static URL validateHostPortString(String hostPort) {
        if (StringUtils.isNullOrWhitespaceOnly(hostPort)) {
            throw new IllegalArgumentException("hostPort should not be null or empty");
        }
        try {
            URL u =
                    (hostPort.toLowerCase().startsWith("http://")
                                    || hostPort.toLowerCase().startsWith("https://"))
                            ? new URL(hostPort)
                            : new URL("http://" + hostPort);
            if (u.getHost() == null) {
                throw new IllegalArgumentException(
                        "The given host:port ('" + hostPort + "') doesn't contain a valid host");
            }
            if (u.getPort() == -1) {
                throw new IllegalArgumentException(
                        "The given host:port ('" + hostPort + "') doesn't contain a valid port");
            }
            return u;
        } catch (MalformedURLException e) {
            throw new IllegalArgumentException(
                    "The given host:port ('" + hostPort + "') is invalid", e);
        }
    }

    /**
     * Converts an InetSocketAddress to a URL. This method assigns the "http://" schema to the URL
     * by default.
     *
     * @param socketAddress the InetSocketAddress to be converted

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Check the echoed value in the message and find which config option/variable produced an empty host.
2. Fix the string so it is 'host:port' (e.g. 'localhost:8081') or a full 'http://host:port' URL.
3. If the host comes from an environment variable or template, assert it is non-empty before building the hostPort string.

Example fix

// before
String hostPort = "http://" + hostVar + ":8081"; // hostVar was ""

// after
Preconditions.checkArgument(!hostVar.isEmpty(), "host must be set");
String hostPort = "http://" + hostVar + ":8081";

// before calling a host:port API
static boolean hasHostPort(String s) {
    try {
        java.net.URL u = new java.net.URL(s.startsWith("http") ? s : "http://" + s);
        return u.getHost() != null && !u.getHost().isEmpty();
    } catch (java.net.MalformedURLException e) { return false; }
}

catch (IllegalArgumentException e) { if (e.getMessage().contains("valid host")) { /* fix config, fail fast with context */ } throw e; }

When it happens

Trigger: Passing a string that URL-parses but carries no host, e.g. 'http:///path', ':8081', or a URL whose authority is empty, to NetUtils host:port parsing (validateHostPortString callers such as the hostPort-parsing utilities used by client/REST address configs).

Common situations: jobmanager.rpc.address / rest.address style configs assembled from variables that come out empty; a service-discovery endpoint returning 'http://' + '' + ':8081'; hand-built strings where the host placeholder was never substituted.

Related errors

• The given host:port ('{}') doesn't contain a valid port
• The given host:port ('{}') is invalid
• The configured hostname is not valid
• Could not parse URL from {url}
• Configuration cannot evaluate value %s as a byte[] value

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/7348329e4eea4dd3. Report an issue: GitHub.