grpc/grpc-java · error · IllegalArgumentException

Unknown denominator type:

Error message

Unknown denominator type: 

What it means

parseFractionMatcher maps the Envoy FractionalPercent denominator (HUNDRED, TEN_THOUSAND, MILLION) to an integer divisor; UNRECOGNIZED or unknown denominator values trigger this IllegalArgumentException. The runtime_fraction config references a denominator type the client cannot map.

Solutions

1. Fix the denominator in the xDS config to a valid value: HUNDRED, TEN_THOUSAND, or MILLION
2. Upgrade grpc-xds if a legitimately new denominator case is in use
3. Validate enum fields on the management server before emitting config
4. Check for proto wire corruption between control plane and client

Example fix

// before
{"numerator":10,"denominator":"UNRECOGNIZED"}
// after
{"numerator":10,"denominator":"HUNDRED"}

int d = proto.getDenominatorValue();
if (d != 0 && d != 1 && d != 2) { reject("invalid denominator"); } // HUNDRED, TEN_THOUSAND, MILLION

null

try { fm = MatcherParser.parseFractionMatcher(proto); }
catch (IllegalArgumentException e) { log.error("Bad denominator: " + e.getMessage()); useDefaultFraction(); }

When it happens

Trigger: A FractionalPercent proto in runtime_fraction config has denominator set to UNRECOGNIZED (invalid wire value) or a case unknown to this parser version.

Common situations: Corrupted or hand-edited config with an out-of-range enum; control plane built against a newer Envoy API adding denominator cases; protobuf decode of a bad wire value yielding UNRECOGNIZED.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown header matcher type:
• Unknown StringMatcher match pattern:
• Failed to parse envoy.config.core.v3.Address: Address field…
• Failed to parse envoy.config.core.v3.Address: Invalid IP…
• Failed to parse envoy.config.core.v3.Address: Port value

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

Appendix: source

Thrown at xds/src/main/java/io/grpc/xds/internal/MatcherParser.java:161

  }

  /** Translates envoy proto FractionalPercent to internal FractionMatcher. */
  public static Matchers.FractionMatcher parseFractionMatcher(
      io.envoyproxy.envoy.type.v3.FractionalPercent proto) {
    int denominator;
    switch (proto.getDenominator()) {
      case HUNDRED:
        denominator = 100;
        break;
      case TEN_THOUSAND:
        denominator = 10_000;
        break;
      case MILLION:
        denominator = 1_000_000;
        break;
      case UNRECOGNIZED:
      default:
        throw new IllegalArgumentException("Unknown denominator type: " + proto.getDenominator());
    }
    return Matchers.FractionMatcher.create(proto.getNumerator(), denominator);
  }
}

View on GitHub (pinned to 64daddc1f3)