apache/druid · error · DruidException

subnet arg has an invalid format: %s

Error message

subnet arg has an invalid format: %s

What it means

IPV4_MATCH's subnet argument must be a string literal in valid IPv4 CIDR form (e.g. 10.0.0.0/8). getSubnetInfo checks the literal with IPv4AddressExprUtils.isValidIPv4Subnet and throws a validation failure when it does not parse, so an invalid subnet never reaches the matcher.

Source

Thrown at processing/src/main/java/org/apache/druid/query/expression/IPv4AddressMatchExprMacro.java:140

        }
      }

      return new IPv4AddressMatchExpr(args);
    }

    catch (AddressStringException e) {
      throw processingFailed(e, "failed to parse address");
    }
  }

  private IPAddressString getSubnetInfo(List<Expr> args)
  {
    String subnetArgName = "subnet";
    Expr arg = args.get(ARG_SUBNET);
    validationHelperCheckArgIsLiteral(arg, subnetArgName);
    String subnet = (String) arg.getLiteralValue();
    if (!IPv4AddressExprUtils.isValidIPv4Subnet(subnet)) {
      throw validationFailed(subnetArgName + " arg has an invalid format: " + subnet);
    }
    return new IPAddressString(subnet);
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Use proper CIDR notation with an explicit prefix: IPV4_MATCH(addr, '10.0.0.0/8').
2. Verify the prefix length is a decimal number between 0 and 32 with no leading zeros or stray characters.
3. Confirm the argument is a string literal; if it comes from a variable, validate it with IPv4AddressExprUtils.isValidIPv4Subnet before substitution.

Example fix

-- before
SELECT IPV4_MATCH(ip, '10.0.0.0') FROM t
-- after
SELECT IPV4_MATCH(ip, '10.0.0.0/8') FROM t

// Java
if (!IPv4AddressExprUtils.isValidIPv4Subnet(subnet)) { throw new IllegalArgumentException("subnet must be valid IPv4 CIDR: " + subnet); }

static boolean isValidIpv4Cidr(String s) {
  return s != null && s.matches("^(\\d{1,3}\\.){3}\\d{1,3}/(\\d{1,2})$") && validPrefix(s);
}

try {
  return runDruidQuery(query);
} catch (ExpressionValidationException e) {
  if (e.getMessage().contains("invalid format")) {
    throw new UserInputException("IPV4_MATCH subnet must be CIDR like 10.0.0.0/8");
  }
  throw e;
}

When it happens

Trigger: Calling IPV4_MATCH(addr, '<subnet>') where the second argument is a literal that fails isValidIPv4Subnet: missing '/prefix', prefix out of 0-32, non-numeric octets, an IPv6 subnet, or an empty string.

Common situations: Typos like '10.0.0.0/08' or '192.168.1/24'; passing a bare address '10.0.0.1' with no /prefix when a subnet is required; quoting errors that make the subnet an empty or concatenated string.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• subnet arg has an invalid format: %s
• Invalid expression: %s; %s used as both scalar and array var
• rank must be a number
• failed to parse address
• escape must be null or a single character

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/d20aff6ce11eda08. Report an issue: GitHub.