grpc/grpc-java · error · ExtAuthzParseException

${e.getMessage()}

Error message

${e.getMessage()}

What it means

When the ext_authz proto has a filter_enabled RuntimeFractionalPercent, ExtAuthzConfigParser parses it with MatcherParser.parseFractionMatcher; an IllegalArgumentException (invalid numerator/denominator or unsupported percentage format) is rethrown as ExtAuthzParseException with the original message. It indicates the fractional-percent matcher in the filter config is numerically invalid.

Source

Thrown at xds/src/main/java/io/grpc/xds/ExtAuthzConfigParser.java:73

    GrpcServiceConfig grpcServiceConfig;
    try {
      grpcServiceConfig =
          GrpcServiceConfigParser.parse(extAuthzProto.getGrpcService(), bootstrapInfo, serverInfo);
    } catch (GrpcServiceParseException e) {
      throw new ExtAuthzParseException("Failed to parse GrpcService config: " + e.getMessage(), e);
    }
    ExtAuthzConfig.Builder builder = ExtAuthzConfig.builder().grpcService(grpcServiceConfig)
        .failureModeAllow(extAuthzProto.getFailureModeAllow())
        .failureModeAllowHeaderAdd(extAuthzProto.getFailureModeAllowHeaderAdd())
        .includePeerCertificate(extAuthzProto.getIncludePeerCertificate())
        .denyAtDisable(extAuthzProto.getDenyAtDisable().getDefaultValue().getValue());

    if (extAuthzProto.hasFilterEnabled()) {
      try {
        builder.filterEnabled(
            MatcherParser.parseFractionMatcher(extAuthzProto.getFilterEnabled().getDefaultValue()));
      } catch (IllegalArgumentException e) {
        throw new ExtAuthzParseException(e.getMessage());
      }
    }

    if (extAuthzProto.hasStatusOnError()) {
      builder.statusOnError(
          GrpcUtil.httpStatusToGrpcStatus(extAuthzProto.getStatusOnError().getCodeValue()));
    }

    if (extAuthzProto.hasAllowedHeaders()) {
      builder.allowedHeaders(extAuthzProto.getAllowedHeaders().getPatternsList().stream()
          .map(MatcherParser::parseStringMatcher).collect(ImmutableList.toImmutableList()));
    }

    if (extAuthzProto.hasDisallowedHeaders()) {
      builder.disallowedHeaders(extAuthzProto.getDisallowedHeaders().getPatternsList().stream()
          .map(MatcherParser::parseStringMatcher).collect(ImmutableList.toImmutableList()));
    }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Read e.getMessage() to see which value was rejected and correct the filter_enabled FractionalPercent in the LDS config.
2. Ensure numerator is 0..denominator (0-100 for HUNDRED, 0-10000 for TEN_THOUSAND, 0-1000000 for MILLION).
3. If you don't need percentage rollout, remove filter_enabled entirely so the filter applies to all requests.
4. Upgrade grpc-java xDS if the control plane emits newer FractionalPercent variants.

Example fix

// before
"filterEnabled": { "defaultValue": { "numerator": 150, "denominator": "HUNDRED" } }
// after
"filterEnabled": { "defaultValue": { "numerator": 100, "denominator": "HUNDRED" } }

static void checkFractionalPercent(int numerator, String denominator) {
  int max = switch (denominator) { case "HUNDRED" -> 100; case "TEN_THOUSAND" -> 10000; case "MILLION" -> 1000000; default -> -1; };
  if (max < 0 || numerator < 0 || numerator > max) throw new IllegalArgumentException("bad fraction");
}

try { /* start xDS */ } catch (ExtAuthzParseException e) { log.error("filter_enabled invalid: {}", e.getMessage()); }

When it happens

Trigger: LDS config where ext_authz.filter_enabled.defaultValue contains a FractionalPercent with an out-of-range numerator or a denominator the parser can't handle; parse() calls MatcherParser.parseFractionMatcher which throws IllegalArgumentException.

Common situations: Control plane sends filter_enabled with e.g. numerator 200 and denominator HUNDRED, or an unset/invalid default value; hand-edited Envoy filter configs; version mismatches where newer percentage semantics aren't supported by the client.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Failed to parse GrpcService config: ${e.getMessage()}
• Unknown denominator type: ${proto.getDenominator()}
• Invalid Resource in address proto
• Audience URL is empty. Metadata value must contain a valid U
• Failed to parse access token credentials: " + e.getMessage()

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/0e6753805331ff9f. Report an issue: GitHub.