apache/cassandra · error · IllegalArgumentException

Invalid netmask <netMask> for IP <hostAddress>

Error message

Invalid netmask <netMask> for IP <hostAddress>

What it means

CIDR's constructor validates that the netmask length is legal for the address family: at most 32 bits for IPv4 and 128 for IPv4-mapped/IPv6 (see maxNetMaskAllowed). A CIDR(inetAddress, netMask) call with a mask longer than the family allows throws IllegalArgumentException 'Invalid netmask <mask> for IP <ip>'.

Source

Thrown at src/java/org/apache/cassandra/cql3/CIDR.java:46

/**
 * Contains a CIDR, and operations on it
 */
public final class CIDR
{
    private final InetAddress startIpAddress;
    private final InetAddress endIpAddress;
    // max mask value with IPv6 is 128, not easy to handle value 128 using Byte, hence using short
    private final short netMask;

    /**
     * Generates a CIDR from given IP and netmask
     * @param ipAddress IP address of CIDR
     * @param netMask   netmask of CIDR
     */
    public CIDR(InetAddress ipAddress, short netMask)
    {
        if (netMask > maxNetMaskAllowed(ipAddress))
            throw new IllegalArgumentException("Invalid netmask " + netMask + " for IP " + ipAddress.getHostAddress());

        Pair<InetAddress, InetAddress> ipRange = calcIpRangeOfCidr(ipAddress, netMask);
        this.startIpAddress = ipRange.left();
        this.endIpAddress = ipRange.right();
        this.netMask = netMask;
    }

    /**
     * Generates a CIDR from given string
     * @param cidrStr CIDR as string
     */
    public static CIDR getInstance(String cidrStr)
    {
        if (cidrStr == null || cidrStr.isEmpty())
        {
            throw new IllegalArgumentException(String.format("%s is not a valid CIDR String", cidrStr));
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Validate the mask before construction: 0 <= mask <= 32 for IPv4, 0 <= mask <= 128 for IPv6
2. Fix the offending entry in the CIDR configuration (cassandra.yaml cidr_allowlist / role CIDR filters)
3. Normalize IPv4-mapped IPv6 addresses and their masks consistently before constructing
4. Wrap CIDR parsing in a helper that throws a clear config error naming the bad rule

Example fix

// before
CIDR cidr = new CIDR(InetAddress.getByName("10.0.0.1"), (short) 33); // throws
// after
short mask = 24;
assert mask >= 0 && mask <= 32; // IPv4 limit
CIDR cidr = new CIDR(InetAddress.getByName("10.0.0.1"), mask);

void validateCidr(java.net.InetAddress ip, short mask) {
    int max = ip.getAddress().length == 4 ? 32 : 128;
    if (mask < 0 || mask > max)
        throw new IllegalArgumentException("netmask /" + mask + " invalid for " + ip.getHostAddress() + " (max " + max + ")");
}

boolean isValidNetmask(java.net.InetAddress ip, short mask) {
    return mask >= 0 && mask <= (ip.getAddress().length == 4 ? 32 : 128);
}

try {
    CIDR cidr = new CIDR(ip, netMask);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid netmask"))
        log.error("Fix CIDR rule: " + e.getMessage());
    throw e;
}

When it happens

Trigger: Calling new CIDR(InetAddress, short) with e.g. netMask 33 for an IPv4 address or 129 for IPv6; parsing user-supplied CIDR strings like '10.0.0.0/33' before constructing; config-driven endpoint filtering rules with out-of-range masks.

Common situations: Typo in cidr_allow/cidr_filter configuration entries; scripts generating masks from wrong-width counts; mixing IPv4/IPv6 assumptions when computing default masks.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid IP %s
• CIDR group '%s' doesn't exists
• Configured ${configName} "${intf}" could not be found
• Configured ${configName} "${intf}" was found, but had no add
• Configured ${configName} "${intf}" caused an exception

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/8356e702b0ec172b. Report an issue: GitHub.