{"record":{"id":"a1b6740140afce54","repo":"apache/flink","slug":"the-configured-hostname-is-not-valid","errorCode":null,"errorMessage":"The configured hostname is not valid","messagePattern":"The configured hostname is not valid","errorType":"validation","errorClass":"IllegalConfigurationException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/NetUtils.java","lineNumber":249,"sourceCode":"                }\n            }\n        }\n\n        // normalize and valid address\n        if (InetAddresses.isInetAddress(host)) {\n            InetAddress inetAddress = InetAddresses.forString(host);\n            if (inetAddress instanceof Inet6Address) {\n                byte[] ipV6Address = inetAddress.getAddress();\n                host = getIPv6UrlRepresentation(ipV6Address);\n            }\n        } else {\n            try {\n                // We don't allow these in hostnames\n                Preconditions.checkArgument(!host.startsWith(\".\"));\n                Preconditions.checkArgument(!host.endsWith(\".\"));\n                Preconditions.checkArgument(!host.contains(\":\"));\n            } catch (Exception e) {\n                throw new IllegalConfigurationException(\"The configured hostname is not valid\", e);\n            }\n        }\n\n        return host;\n    }\n\n    /**\n     * Returns a valid address for Pekko. It returns a String of format 'host:port'. When an IPv6\n     * address is specified, it normalizes the IPv6 address to avoid complications with the exact\n     * URL match policy of Pekko.\n     *\n     * @param host The hostname, IPv4 or IPv6 address\n     * @param port The port\n     * @return host:port where host will be normalized if it is an IPv6 address\n     */\n    public static String unresolvedHostAndPortToNormalizedString(String host, int port) {\n        Preconditions.checkArgument(isValidHostPort(port), \"Port is not within the valid range,\");\n        return unresolvedHostToNormalizedString(host) + \":\" + port;","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/NetUtils.java#L231-L267","documentation":"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.","triggerScenarios":"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.","commonSituations":"DNS-derived names with trailing dot; IPv6 configured in a hostname field without brackets; template artifacts producing leading dots; misconfigured kubernetes/network configs.","solutions":["Strip leading/trailing dots from the configured hostname.","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.","Check the exact config key quoted in the stack trace and correct its value."],"exampleFix":"# before\nrest.address: myhost.example.com.\n\n# after\nrest.address: myhost.example.com","handlingStrategy":"validation","validationCode":"static String normalizeHostCandidate(String host) {\n    String h = host.trim();\n    Preconditions.checkArgument(!h.startsWith(\".\") && !h.endsWith(\".\"), \"bad hostname: %s\", h);\n    Preconditions.checkArgument(h.indexOf(':') < 0 || h.contains(\"]\"), \"IPv6 must be a literal, not a hostname: %s\", h);\n    return h;\n}","typeGuard":null,"tryCatchPattern":"catch (IllegalConfigurationException e) { fail startup with the config key and value so operators can fix the hostname; do not retry blindly. }","preventionTips":["Lint hostname configs: no leading/trailing dots.","Configure IPv6 addresses as IP literals, never in hostname fields."],"tags":["network","configuration","hostname","ipv6","flink-core"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}