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.

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 configured hostname is not valid
• The given host:port (' ') is invalid
• Address cannot be resolved
• address is null

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

Appendix: 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)