grpc/grpc-java · error · IllegalArgumentException

OrMatcher must have at least 2 predicates

Error message

OrMatcher must have at least 2 predicates

What it means

An OrMatcherEvaluator represents a PredicateList under or_matcher; matching against zero or one predicate is meaningless (an OR of one term is that term). The constructor throws IllegalArgumentException when the proto has fewer than 2 predicates.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/matcher/PredicateEvaluator.java:119

              "StringMatcher expected a String input, but received: " 
              + value.getClass().getName());
        }
        return stringMatcher.matches((String) value);
      }

      @Override
      public Class<?> inputType() {
        return String.class;
      }
    }
  }
  
  private static final class OrMatcherEvaluator extends PredicateEvaluator {
    private final List<PredicateEvaluator> evaluators;
    
    OrMatcherEvaluator(Predicate.PredicateList proto) {
      if (proto.getPredicateCount() < 2) {
        throw new IllegalArgumentException("OrMatcher must have at least 2 predicates");
      }
      this.evaluators = new ArrayList<>(proto.getPredicateCount());
      for (Predicate p : proto.getPredicateList()) {
        evaluators.add(PredicateEvaluator.fromProto(p));
      }
    }
    
    @Override 
    boolean evaluate(MatchContext context) {
      for (PredicateEvaluator e : evaluators) {
        if (e.evaluate(context)) {
          return true;
        }
      }
      return false;
    }
  }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Ensure or_matcher contains at least 2 predicates in the config
2. Replace single-predicate or_matcher usage with the predicate directly
3. Pre-validate PredicateList counts before parsing the matcher tree

Example fix

// before
or_matcher:
  predicate:
  - single_predicate: { ... }
// after: use the predicate directly, or add a second clause
or_matcher:
  predicate:
  - single_predicate: { ... }
  - single_predicate: { ... }

if (proto.getPredicateCount() < 2) {
  throw new IllegalArgumentException("or_matcher requires >= 2 predicates");
}

try { new PredicateEvaluator.OrMatcherEvaluator(proto); } catch (IllegalArgumentException e) { log.warn("or_matcher with <2 predicates: " + e.getMessage()); }

When it happens

Trigger: Building OrMatcherEvaluator from a Predicate.PredicateList proto with getPredicateCount() < 2 — e.g. or_matcher set to an empty list, or a single-element list where the author should have used the predicate directly.

Common situations: Control-plane config generators emitting or_matcher with one clause; config simplification tools that stripped duplicate predicates; hand-written configs that over-nested a single condition into an or_matcher.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Predicate must have one of: single_predicate, or_matcher, an
• SinglePredicate must have input
• SinglePredicate must have either value_match or custom_match
• AndMatcher must have at least 2 predicates
• unsupported ExtAuthz service type: only grpc_service is supp

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