apache/flink · error · IllegalArgumentException

Unrecognized type of InetAddress: {}

Error message

Unrecognized type of InetAddress: {}

What it means

NetUtils.ipAddressToUrlString handles exactly Inet4Address and Inet6Address; any other InetAddress subclass triggers IllegalArgumentException with the object printed. The JDK only produces those two in practice, so this guard fires almost exclusively on custom InetAddress subclasses passed by user code.

Source

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

        return unresolvedHostToNormalizedString(host) + ":" + port;
    }

    /**
     * Encodes an IP address properly as a URL string. This method makes sure that IPv6 addresses
     * have the proper formatting to be included in URLs.
     *
     * @param address The IP address to encode.
     * @return The proper URL string encoded IP address.
     */
    public static String ipAddressToUrlString(InetAddress address) {
        if (address == null) {
            throw new NullPointerException("address is null");
        } else if (address instanceof Inet4Address) {
            return address.getHostAddress();
        } else if (address instanceof Inet6Address) {
            return getIPv6UrlRepresentation((Inet6Address) address);
        } else {
            throw new IllegalArgumentException("Unrecognized type of InetAddress: " + address);
        }
    }

    /**
     * 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 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.

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Convert the custom object to a real address first: InetAddress.getByName(custom.getHostName()) or InetAddress.getByAddress(custom.getAddress()).
2. In tests, mock with concrete Inet4Address/Inet6Address instances (e.g. InetAddress.getByName("127.0.0.1")) instead of subclass mocks.

Example fix

// before
NetUtils.ipAddressToUrlString(mockAddr); // mockAddr extends InetAddress

// after
InetAddress real = InetAddress.getByAddress(mockAddr.getAddress());
NetUtils.ipAddressToUrlString(real);

static boolean isSupportedInetAddress(InetAddress a) { return a instanceof Inet4Address || a instanceof Inet6Address; }

if (!(addr instanceof Inet4Address) && !(addr instanceof Inet6Address)) { addr = InetAddress.getByAddress(addr.getAddress()); } // normalize before use

When it happens

Trigger: Passing a hand-written InetAddress subclass (e.g. a mock in tests or a custom InetAddr implementation overriding getAddress) into ipAddressToUrlString or ipAddressAndPortToUrlString.

Common situations: Unit tests stubbing InetAddress with Mockito/Spy subclasses; exotic JVMs or libraries introducing non-standard address types; copying addresses between frameworks that wrap them.

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/cca24f77637927b1. Report an issue: GitHub.