apache/flink · error · IllegalArgumentException

Address cannot be resolved: {}

Error message

Address cannot be resolved: {}

What it means

NetUtils.socketAddressToUrlString requires a resolved InetSocketAddress; if it was created from a hostname that DNS could not resolve, isUnresolved() is true and this IllegalArgumentException is thrown with the unresolved host string. Flink needs the concrete IP to build the URL representation (including IPv6 formatting). It usually surfaces an upstream DNS failure.

Source

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

     *
     * @param address The address to be included in the URL.
     * @param port The port for the URL address.
     * @return The proper URL string encoded IP address and port.
     */
    public static String ipAddressAndPortToUrlString(InetAddress address, int port) {
        return ipAddressToUrlString(address) + ':' + port;
    }

    /**
     * Encodes an IP address and port to be included in URL. in particular, this method makes sure
     * that IPv6 addresses have the proper formatting to be included in URLs.
     *
     * @param address The socket address with the IP address and port.
     * @return The proper URL string encoded IP address and port.
     */
    public static String socketAddressToUrlString(InetSocketAddress address) {
        if (address.isUnresolved()) {
            throw new IllegalArgumentException(
                    "Address cannot be resolved: " + address.getHostString());
        }
        return ipAddressAndPortToUrlString(address.getAddress(), address.getPort());
    }

    /**
     * Normalizes and encodes a hostname and port to be included in URL. In particular, this method
     * makes sure that IPv6 address literals have the proper formatting to be included in URLs.
     *
     * @param host The address to be included in the URL.
     * @param port The port for the URL address.
     * @return The proper URL string encoded IP address and port.
     * @throws java.net.UnknownHostException Thrown, if the hostname cannot be translated into a
     *     URL.
     */
    public static String hostAndPortToUrlString(String host, int port) throws UnknownHostException {
        return ipAddressAndPortToUrlString(InetAddress.getByName(host), port);
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the hostname resolves from the machine throwing the error (nslookup/getent hosts).
2. Fix DNS/hosts entries or use IP addresses / properly configured service discovery.
3. Resolve explicitly with InetAddress.getByName and construct the socket address from the InetAddress so failures happen as UnknownHostException with clearer context.

Example fix

// before
InetSocketAddress sa = new InetSocketAddress(host, port);
String url = NetUtils.socketAddressToUrlString(sa); // throws if DNS failed

// after
InetAddress addr = InetAddress.getByName(host); // throws UnknownHostException early
InetSocketAddress sa = new InetSocketAddress(addr, port);
String url = NetUtils.socketAddressToUrlString(sa);

static InetSocketAddress requireResolved(String host, int port) throws UnknownHostException {
    InetAddress a = InetAddress.getByName(host); // throws early with clear context
    return new InetSocketAddress(a, port);
}

if (socketAddress.isUnresolved()) { throw new UnknownHostException("cannot resolve " + socketAddress.getHostString()); } // before calling socketAddressToUrlString

When it happens

Trigger: new InetSocketAddress("unknown.host.example", 8081) followed by socketAddressToUrlString; hostname resolved at object creation but lookup silently failed, leaving address null inside the socket address.

Common situations: Kubernetes/Docker service names not resolvable from the JobManager; /etc/hosts or DNS misconfiguration; a task manager registering with a name the client cannot resolve; transient DNS outage at startup.

Related errors

• The given host:port ('{}') doesn't contain a valid host
• The given host:port ('{}') doesn't contain a valid port
• The given host:port ('{}') is invalid
• Could not find a free permitted port on the machine.
• The configured hostname is not valid

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