apache/flink · error · IllegalConfigurationException

The configured hostname is not valid

Error message

The configured hostname is not valid

What it means

NetUtils host normalization (unresolvedHostToNormalizedString path) validates that a non-IP-literal hostname neither starts with nor ends with a dot and contains no colon; violations are wrapped into IllegalConfigurationException. The colon check exists because an unbracketed IPv6 literal cannot be a hostname. It indicates the hostname field of a config (e.g. an address option) holds a malformed value.

Source

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

                }
            }
        }

        // normalize and valid address
        if (InetAddresses.isInetAddress(host)) {
            InetAddress inetAddress = InetAddresses.forString(host);
            if (inetAddress instanceof Inet6Address) {
                byte[] ipV6Address = inetAddress.getAddress();
                host = getIPv6UrlRepresentation(ipV6Address);
            }
        } else {
            try {
                // We don't allow these in hostnames
                Preconditions.checkArgument(!host.startsWith("."));
                Preconditions.checkArgument(!host.endsWith("."));
                Preconditions.checkArgument(!host.contains(":"));
            } catch (Exception e) {
                throw new IllegalConfigurationException("The configured hostname is not valid", e);
            }
        }

        return host;
    }

    /**
     * Returns a valid address for Pekko. It returns a String of format 'host:port'. When an IPv6
     * address is specified, it normalizes the IPv6 address to avoid complications with the exact
     * URL match policy of Pekko.
     *
     * @param host The hostname, IPv4 or IPv6 address
     * @param port The port
     * @return host:port where host will be normalized if it is an IPv6 address
     */
    public static String unresolvedHostAndPortToNormalizedString(String host, int port) {
        Preconditions.checkArgument(isValidHostPort(port), "Port is not within the valid range,");
        return unresolvedHostToNormalizedString(host) + ":" + port;

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Strip leading/trailing dots from the configured hostname.
2. If the value is an IPv6 address, supply it as the IP literal (the InetAddresses branch normalizes it) rather than as a hostname with colons.
3. Check the exact config key quoted in the stack trace and correct its value.

Example fix

# before
rest.address: myhost.example.com.

# after
rest.address: myhost.example.com

static String normalizeHostCandidate(String host) {
    String h = host.trim();
    Preconditions.checkArgument(!h.startsWith(".") && !h.endsWith("."), "bad hostname: %s", h);
    Preconditions.checkArgument(h.indexOf(':') < 0 || h.contains("]"), "IPv6 must be a literal, not a hostname: %s", h);
    return h;
}

catch (IllegalConfigurationException e) { fail startup with the config key and value so operators can fix the hostname; do not retry blindly. }

When it happens

Trigger: Hostname values like '.myhost', 'myhost.', or 'fe80::1' passed to the Pekko/URL host normalization used when building RPC/REST addresses; a Fully-Qualified Domain Name with a trailing dot from DNS or a copy-paste error.

Common situations: DNS-derived names with trailing dot; IPv6 configured in a hostname field without brackets; template artifacts producing leading dots; misconfigured kubernetes/network configs.

Related errors

• fqdn is null
• 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
• Configuration cannot evaluate value %s as a byte[] value

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