apache/druid · error · DruidException

failed to parse address

Error message

failed to parse address

What it means

The IPV6_MATCH expression macro parses its arguments with IPAddressString at macro-apply time; any exception during that parse is rethrown as a processing failure with message 'failed to parse address'. This guards against addresses that the underlying library cannot even interpret (not merely addresses that fail the match).

Solutions

1. Validate the column or literal with IPv6AddressExprUtils.isValidIPv6(value) before using IPV6_MATCH.
2. Clean the data upstream: strip zone IDs/ports and normalize to canonical IPv6 notation.
3. If a literal, verify correct bracketing/escaping of the IPv6 string in your query JSON or SQL.

Example fix

-- before
SELECT IPV6_MATCH(ip, 'fe80::1%eth0/64') FROM t
-- after
SELECT IPV6_MATCH(ip, 'fe80::/64') FROM t

// Java
if (!IPv6AddressExprUtils.isValidIPv6(candidate)) { throw new IllegalArgumentException("not a valid IPv6 address: " + candidate); }

static boolean looksLikeIPv6(String s) {
  return s != null && s.contains(":") && !s.contains("%");
}

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

When it happens

Trigger: Invoking IPV6_MATCH with an address or subnet expression whose value triggers a parse exception inside IPAddressString, e.g. malformed IPv6 text with invalid groups, double colons in wrong positions, or an address embedded with a scope/zone id in an unsupported form.

Common situations: Ingesting IPv6 data with junk values (':::', 'fe80::1%eth0' variants) and running IPV6_MATCH over the column; hand-written expressions where the address literal was mis-escaped; mixed IPv4-in-IPv6 strings that the library rejects.

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 address
• Failed to parse expression
• subnet arg has an invalid format
• attempt to get boolean[] null vector from string[] only…
• attempt to get double[] from string[] only scalar binding

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

Appendix: source

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

        private boolean isStringMatch(String stringValue)
        {
          IPAddressString addressString = IPv6AddressExprUtils.parseString(stringValue);
          return addressString != null && blockString.prefixContains(addressString);
        }

        @Nullable
        @Override
        public ExpressionType getOutputType(InputBindingInspector inspector)
        {
          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)