apache/flink · error · IllegalArgumentException

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

Error message

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

What it means

After NetUtils.validateHostPortString successfully builds a URL, it requires an explicit port: URL.getPort() == -1 means no ':port' was present in the authority. A host-only string like 'localhost' is therefore rejected even though it is a valid host, because the Flink APIs using this validation need a concrete endpoint. The message includes the offending input.

Source

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

     *
     * @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
     * @return a URL object representing the provided socket address with "http://" schema
     */
    public static URL socketToUrl(InetSocketAddress socketAddress) {
        String hostString = socketAddress.getHostString();

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Append the port to the string: 'myhost:8081' instead of 'myhost'.
2. If a default port applies, add it when building the string rather than relying on Flink to assume one.
3. Verify no typo swallowed the port (e.g. 'myhost::8081' or 'myhost 8081').

Example fix

// before
String address = "jobmanager.host"; // no port

// after
String address = "jobmanager.host:6123";

static void requireHostAndPort(String hostPort) {
    String s = hostPort.replaceFirst("^https?://", "");
    int i = s.lastIndexOf(':');
    Preconditions.checkArgument(i > 0, "missing port in %s", hostPort);
    Preconditions.checkArgument(s.substring(i + 1).chars().allMatch(Character::isDigit),
            "port not numeric in %s", hostPort);
}

catch (IllegalArgumentException e) { log.error("endpoint {} lacks a port; expected host:port", value, e); throw e; }

When it happens

Trigger: Calling a host:port-parsing API with 'myhost', 'http://myhost' (no port), or a port that is not numeric so the URL treats the suffix as part of the path/authority without a port.

Common situations: Configuring a REST/RPC address with a hostname only; YAML placeholders like ${HOST} where the ':${PORT}' suffix was dropped; passing 'jobmanager.rpc.address' value where a port was expected alongside it.

Related errors

• The given host:port ('{}') doesn't contain a valid host
• 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/b7e4416b45c1436f. Report an issue: GitHub.