apache/druid · error · DruidException

failed to parse address

Error message

failed to parse address

What it means

The IPV4_MATCH expression macro uses the IPAddressString library to parse its address argument during compilation. If the underlying IPAddressString raises an AddressStringException while interpreting the address/subnet, Druid wraps it as an expression processing failure with message 'failed to parse address'.

Source

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

        private boolean isLongMatch(long longValue)
        {
          IPv4Address address = IPv4AddressExprUtils.parse(longValue);
          return address != null && block.contains(address);
        }

        @Nullable
        @Override
        public ExpressionType getOutputType(InputBindingInspector inspector)
        {
          return ExpressionType.LONG;
        }
      }

      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. Validate the input with IPv4AddressExprUtils.isValidIPv4(addr) (or a regex like ^(\d{1,3}\.){3}\d{1,3}$) before passing it to IPV4_MATCH.
2. Normalize the address string (trim whitespace, strip port/zone suffixes) upstream in your ingestion or query-building code.
3. Ensure the first argument resolves to a plain IPv4 string at evaluation time; check the column's values for junk rows.

Example fix

// before
expr = "IPV4_MATCH(ip, '10.0.0.0/8')"; // ip may contain junk like '10.0.0.1:80'
// after
expr = "IPV4_MATCH(REGEXP_EXTRACT(ip, '^((\\d{1,3}\\.){3}\\d{1,3})', 1), '10.0.0.0/8')"

// Java
if (!IPv4AddressExprUtils.isValidIPv4(candidate)) { throw new IllegalArgumentException("not a valid IPv4 address: " + candidate); }

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

try {
  return evalExpression(expr);
} catch (ExpressionProcessingException e) {
  if (e.getMessage().contains("failed to parse address")) {
    log.warn("Skipping unparseable IP value");
    return null;
  }
  throw e;
}

When it happens

Trigger: Invoking IPV4_MATCH with an address expression or literal that the IPAddress library cannot parse at apply-time, e.g. malformed IPv4 input that trips AddressStringException rather than merely returning false.

Common situations: Feeding raw, unvalidated user-supplied IP strings into IPV4_MATCH; regional or unusual address formats (e.g. values with zone IDs or octal segments) that the parsing library rejects as invalid rather than unparseable.

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.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse expression: %s
• subnet arg has an invalid format: %s
• failed to parse address
• Expression %s has non-constant inputs.
• Function[%s] %s

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