apache/flink · error · IllegalArgumentException

The given host:port ('{}') is invalid

Error message

The given host:port ('{}') is invalid

What it means

This IllegalArgumentException wraps a java.net.MalformedURLException raised while NetUtils.validateHostPortString turns the input into a URL. It means the string is not parseable as a URL at all — malformed syntax rather than merely a missing host or port. The original MalformedURLException is attached as the cause for details.

Source

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

            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();
        // If the hostString is an IPv6 address, it needs to be enclosed in square brackets
        // at the beginning and end.
        if (socketAddress.getAddress() != null
                && socketAddress.getAddress() instanceof Inet6Address
                && hostString.equals(socketAddress.getAddress().getHostAddress())) {

View on GitHub (pinned to 2f3c205e92)

Solutions

  1. Read the cause (MalformedURLException) to see where parsing failed.
  2. For IPv6, bracket the address: 'http://[fe80::1]:8081' or '[fe80::1]:8081'.
  3. Trim whitespace and remove duplicate schemes or stray path/query suffixes from the value.
  4. If the field expects bare host:port, do not also include a scheme that conflicts with the auto-prepended one.

Example fix

// before
String address = "fe80::1:8081"; // ambiguous IPv6

// after
String address = "[fe80::1]:8081";
Defensive patterns

Strategy: try-catch

Validate before calling

static boolean isParsableHostPort(String s) {
    try { new java.net.URL(s.startsWith("http") ? s : "http://" + s); return true; }
    catch (java.net.MalformedURLException e) { return false; }
}

Try / catch

try { NetUtils-validating call } catch (IllegalArgumentException e) { Throwable cause = e.getCause(); if (cause instanceof MalformedURLException) { /* report malformed value, keep cause */ } }

Prevention

When it happens

Trigger: Inputs like 'host:8081:extra', an unbracketed IPv6 literal such as 'fe80::1:8081', 'http://host:NotAPort', or strings containing illegal URL characters (spaces, stray slashes) passed to host:port validation.

Common situations: IPv6 addresses used without square brackets; copy-pasted endpoints with trailing paths or whitespace; interpolating a full URL into a field that already gets the 'http://' prefix, producing 'http://http://host:port'.

Related errors

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