apache/dubbo · error · IllegalArgumentException

The host is ipv4, but the pattern is not ipv4 pattern : ${pa

Error message

The host is ipv4, but the pattern is not ipv4 pattern : ${pattern}

What it means

Thrown by NetUtils.matchIpRange when the resolved host address is IPv4 (isIpv4=true) but the supplied IP pattern does not split into exactly 4 dot-separated octets. The library rejects non-quad patterns because it cannot index into the four IPv4 octet segments for range or wildcard matching.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/utils/NetUtils.java:874

    }

    private static boolean ipPatternContainExpression(String pattern) {
        return pattern.contains("*") || pattern.contains("-");
    }

    private static void checkHostPattern(String pattern, String[] mask, boolean isIpv4) {
        if (!isIpv4) {
            if (mask.length != 8 && ipPatternContainExpression(pattern)) {
                throw new IllegalArgumentException(
                        "If you config ip expression that contains '*' or '-', please fill qualified ip pattern like 234e:0:4567:0:0:0:3d:*. ");
            }
            if (mask.length != 8 && !pattern.contains("::")) {
                throw new IllegalArgumentException(
                        "The host is ipv6, but the pattern is not ipv6 pattern : " + pattern);
            }
        } else {
            if (mask.length != 4) {
                throw new IllegalArgumentException(
                        "The host is ipv4, but the pattern is not ipv4 pattern : " + pattern);
            }
        }
    }

    private static String[] getPatternHostAndPort(String pattern, boolean isIpv4) {
        String[] result = new String[2];
        if (pattern.startsWith("[") && pattern.contains("]:")) {
            int end = pattern.indexOf("]:");
            result[0] = pattern.substring(1, end);
            result[1] = pattern.substring(end + 2);
            return result;
        } else if (pattern.startsWith("[") && pattern.endsWith("]")) {
            result[0] = pattern.substring(1, pattern.length() - 1);
            result[1] = null;
            return result;
        } else if (isIpv4 && pattern.contains(":")) {
            int end = pattern.indexOf(":");

View on GitHub (pinned to 3a3043227f)

Solutions

1. Ensure the pattern is a valid dotted-quad IPv4 with exactly 4 groups, using '*' or '-' for wildcards/ranges (e.g. '192.168.1.*' or '192.168.1.10-20').
2. Do not use CIDR notation; matchIpRange expects glob/range patterns, not '/24' suffixes.
3. If the host is actually IPv6, switch the pattern to IPv6 format and vice versa — the address family of the host determines which pattern format is valid.
4. Double-check for trailing dots or extra segments in the pattern string.

Example fix

// before
NetUtils.matchIpRange("192.168.1.0/24", "192.168.1.10", 20880);
// after — use glob format, not CIDR
NetUtils.matchIpRange("192.168.1.*", "192.168.1.10", 20880);

// Validate IPv4 pattern has exactly 4 dot-separated octets
String[] octets = pattern.split("\\.");
if (octets.length != 4) {
    throw new IllegalArgumentException(
        "IPv4 pattern must have 4 octets, got " + octets.length + ": " + pattern);
}
NetUtils.matchIpRange(pattern, host, port);

try {
    return NetUtils.matchIpRange(pattern, host, port);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("not ipv4 pattern")) {
        logger.warn("Invalid IPv4 pattern '{}': expected 4 octets", pattern);
        return false;
    }
    throw e;
}

When it happens

Trigger: Calling NetUtils.matchIpRange(pattern, host, port) where the host resolves to an IPv4 address but the pattern is an IPv6 string, a bare hostname, or a malformed IPv4 with fewer/more than 4 dot-separated groups. Internally, pattern.split('.') must produce mask.length == 4, otherwise checkHostPattern throws.

Common situations: Writing IP allow/deny lists for Dubbo QoS telnet access control or registry filters where a typo produces 3 or 5 octets. Also when a config uses a CIDR notation like '192.168.1.0/24' (which splits into an unexpected group) instead of the wildcard/range format '192.168.1.*' that matchIpRange expects.

Related errors

• The host is ipv6, but the pattern is not ipv6 pattern : ${pa
• not an valid CIDR format!
• Illegal Argument pattern or hostName. Pattern:${pattern}, Ho
• There is wrong format of ip Address: ${mask[i]}
• If you config ip expression that contains '*' or '-', please

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/38e18506f7094043. Report an issue: GitHub.