{"record":{"id":"e6d12b27159b7df1","repo":"apache/dubbo","slug":"the-host-is-ipv6-but-the-pattern-is-not-ipv6-patt","errorCode":null,"errorMessage":"The host is ipv6, but the pattern is not ipv6 pattern : ${pattern}","messagePattern":"The host is ipv6, but the pattern is not ipv6 pattern : (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/utils/NetUtils.java","lineNumber":869,"sourceCode":"                int p = Integer.parseInt(prefix);\n                return p >= 224 && p <= 239;\n            }\n        }\n        return false;\n    }\n\n    private static boolean ipPatternContainExpression(String pattern) {\n        return pattern.contains(\"*\") || pattern.contains(\"-\");\n    }\n\n    private static void checkHostPattern(String pattern, String[] mask, boolean isIpv4) {\n        if (!isIpv4) {\n            if (mask.length != 8 && ipPatternContainExpression(pattern)) {\n                throw new IllegalArgumentException(\n                        \"If you config ip expression that contains '*' or '-', please fill qualified ip pattern like 234e:0:4567:0:0:0:3d:*. \");\n            }\n            if (mask.length != 8 && !pattern.contains(\"::\")) {\n                throw new IllegalArgumentException(\n                        \"The host is ipv6, but the pattern is not ipv6 pattern : \" + pattern);\n            }\n        } else {\n            if (mask.length != 4) {\n                throw new IllegalArgumentException(\n                        \"The host is ipv4, but the pattern is not ipv4 pattern : \" + pattern);\n            }\n        }\n    }\n\n    private static String[] getPatternHostAndPort(String pattern, boolean isIpv4) {\n        String[] result = new String[2];\n        if (pattern.startsWith(\"[\") && pattern.contains(\"]:\")) {\n            int end = pattern.indexOf(\"]:\");\n            result[0] = pattern.substring(1, end);\n            result[1] = pattern.substring(end + 2);\n            return result;\n        } else if (pattern.startsWith(\"[\") && pattern.endsWith(\"]\")) {","sourceCodeStart":851,"sourceCodeEnd":887,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/utils/NetUtils.java#L851-L887","documentation":"Thrown by NetUtils.matchIpRange when the resolved host address is IPv6 (isIpv4=false) but the supplied IP pattern does not look like a valid IPv6 address. Specifically, splitting the pattern by ':' does not yield 8 groups and the pattern does not contain '::' (the IPv6 zero-compression marker). The library rejects it because the pattern cannot be safely matched against the host segments.","triggerScenarios":"Calling NetUtils.matchIpRange(pattern, host, port) where the host resolves to an IPv6 address (e.g. 'fe80::1') but the pattern argument is an IPv4-style string (e.g. '192.168.1.*'), a hostname, or a malformed IPv6 string without '::' that doesn't have 8 colon-separated groups. Internally, getPatternHostAndPort strips brackets, the pattern is split by SPLIT_IPV6_CHARACTER (':'), and if mask.length != 8 and pattern has no '::', checkHostPattern throws.","commonSituations":"Configuring an IP allow/deny list in Dubbo's QoS, registry, orTelnet access control where the server runs on a dual-stack or IPv6-only network but the filter patterns were written for IPv4. Also occurs when copy-pasting IPv4 patterns into a config that targets IPv6 hosts, or when a hostname resolves to an AAAA record and the pattern was written expecting dotted-quad.","solutions":["If the host is genuinely IPv6, supply a fully-qualified 8-group IPv6 pattern (e.g. '234e:0:4567:0:0:0:3d:*') or a pattern containing '::' compression (e.g. '234e::3d:1').","If you intended to match an IPv4 host, verify the host value actually resolves to IPv4 — use an explicit IPv4 literal instead of a hostname to avoid the OS returning an AAAA record.","For wildcard IPv6 patterns with '*' or '-', use the full 8-group form; abbreviated forms without '::' and without 8 groups are rejected (the preceding check at line 864 enforces this).","Review the matchIpRange call site (often in QoS/registry filter config) and align the pattern family with the actual address family of the host."],"exampleFix":"// before\nNetUtils.matchIpRange(\"192.168.1.*\", \"fe80::1\", 20880);\n// after — match against the IPv6 address family\nNetUtils.matchIpRange(\"fe80::*\", \"fe80::1\", 20880);\n// or force IPv4 resolution\nNetUtils.matchIpRange(\"192.168.1.*\", \"192.168.1.10\", 20880);","handlingStrategy":"validation","validationCode":"// Validate pattern matches host address family before calling matchIpRange\nInetAddress addr = InetAddress.getByName(host);\nboolean isIpv4 = addr instanceof Inet4Address;\nif (isIpv4) {\n    String[] octets = pattern.split(\"\\\\.\");\n    if (octets.length != 4) {\n        throw new IllegalArgumentException(\"Pattern must be 4-octet IPv4: \" + pattern);\n    }\n} else {\n    // For IPv6, require 8 groups or '::' compression\n    if (pattern.split(\":\").length < 2 && !pattern.contains(\"::\")) {\n        throw new IllegalArgumentException(\"Pattern must be IPv6 format: \" + pattern);\n    }\n}\nNetUtils.matchIpRange(pattern, host, port);","typeGuard":null,"tryCatchPattern":"try {\n    return NetUtils.matchIpRange(pattern, host, port);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"not ipv6 pattern\") || e.getMessage().contains(\"not ipv4 pattern\")) {\n        logger.warn(\"IP pattern '{}' does not match host '{}' address family\", pattern, host);\n        return false; // or fall back to exact match\n    }\n    throw e;\n}","preventionTips":["Always match the pattern format to the address family of the host — use InetAddress to check IPv4 vs IPv6 first.","Use explicit IP literals rather than hostnames in IP filter patterns to avoid unexpected AAAA/A record resolution.","In config files, document which address family each pattern targets."],"tags":["network","ipv6","ip-filter","config-validation"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}