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).

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)

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 expression: %s
• failed to parse address
• subnet arg has an invalid format: %s
• Expression %s has non-constant inputs.
• Function[%s] %s

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