apache/druid · error · DruidException

subnet arg has an invalid format: %s

Error message

subnet arg has an invalid format: %s

What it means

IPV6_MATCH's subnet argument must be a string literal that passes IPv6AddressExprUtils.isValidIPv6Subnet (valid IPv6 address plus /prefix). getSubnetInfo throws a validation failure naming the offending value when the literal is not a valid IPv6 subnet, preventing downstream parse failures.

Source

Thrown at processing/src/main/java/org/apache/druid/query/expression/IPv6AddressMatchExprMacro.java:119

          return ExpressionType.LONG;
        }
      }

      return new IPv6AddressMatchExpr(args);
    }
    catch (Exception 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 (!IPv6AddressExprUtils.isValidIPv6Subnet(subnet)) {
      throw validationFailed(subnetArgName + " arg has an invalid format: " + subnet);
    }
    return new IPAddressString(subnet);
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Provide full IPv6 CIDR notation, e.g. IPV6_MATCH(addr, '2001:db8::/32').
2. Verify the prefix is a decimal 0-128 and the address part is valid IPv6.
3. If the subnet is dynamic, validate with IPv6AddressExprUtils.isValidIPv6Subnet before building the expression.

Example fix

-- before
SELECT IPV6_MATCH(ip, '2001:db8::1') FROM t
-- after
SELECT IPV6_MATCH(ip, '2001:db8::/32') FROM t

// Java
if (!IPv6AddressExprUtils.isValidIPv6Subnet(subnet)) { throw new IllegalArgumentException("subnet must be valid IPv6 CIDR: " + subnet); }

static boolean isValidIpv6Cidr(String s) {
  int slash = s == null ? -1 : s.lastIndexOf('/');
  return slash > 0 && Integer.parseInt(s.substring(slash + 1)) <= 128 && s.contains(":");
}

try {
  return runDruidQuery(query);
} catch (ExpressionValidationException e) {
  if (e.getMessage().contains("invalid format")) {
    throw new UserInputException("IPV6_MATCH subnet must be IPv6 CIDR like 2001:db8::/32");
  }
  throw e;
}

When it happens

Trigger: Calling IPV6_MATCH(addr, '<subnet>') where the subnet literal is not valid IPv6 CIDR: IPv4 subnet like '10.0.0.0/8', missing prefix like 'fe80::1', prefix >128, or empty/blank string.

Common situations: Copy-pasting IPv4 CIDRs into IPV6_MATCH; forgetting the /prefix on an IPv6 address; template concatenation producing empty subnet strings.

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/bf83538bbb19632e. Report an issue: GitHub.