{"record":{"id":"9809ad3036598cc6","repo":"grpc/grpc-java","slug":"matchertree-prefix-match-map-must-contain-at-least","errorCode":null,"errorMessage":"MatcherTree prefix_match_map must contain at least one entry","messagePattern":"MatcherTree prefix_match_map must contain at least one entry","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/internal/matcher/MatcherTree.java","lineNumber":73,"sourceCode":"    this.input = UnifiedMatcher.resolveInput(proto.getInput());\n    \n    if (proto.hasExactMatchMap()) {\n      Matcher.MatcherTree.MatchMap matchMap = proto.getExactMatchMap();\n      if (matchMap.getMapCount() == 0) {\n        throw new IllegalArgumentException(\n            \"MatcherTree exact_match_map must contain at least one entry\");\n      }\n      this.exactMatchMap = new HashMap<>();\n      for (Map.Entry<String, Matcher.OnMatch> entry : \n          matchMap.getMapMap().entrySet()) {\n        this.exactMatchMap.put(entry.getKey(),\n            new OnMatch(entry.getValue(), actionValidator));\n      }\n      this.prefixTrie = null;\n    } else if (proto.hasPrefixMatchMap()) {\n      Matcher.MatcherTree.MatchMap matchMap = proto.getPrefixMatchMap();\n      if (matchMap.getMapCount() == 0) {\n        throw new IllegalArgumentException(\n            \"MatcherTree prefix_match_map must contain at least one entry\");\n      }\n      this.prefixTrie = new PrefixTrie();\n      for (Map.Entry<String, Matcher.OnMatch> entry : \n          matchMap.getMapMap().entrySet()) {\n        this.prefixTrie.insert(entry.getKey(),\n            new OnMatch(entry.getValue(), actionValidator));\n      }\n      this.exactMatchMap = null;\n    } else {\n      throw new IllegalArgumentException(\n          \"MatcherTree must have either exact_match_map or prefix_match_map\");\n    }\n    if (onNoMatchProto != null) {\n      this.onNoMatch = new OnMatch(onNoMatchProto, actionValidator);\n    } else {\n      this.onNoMatch = null;\n    }","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/internal/matcher/MatcherTree.java#L55-L91","documentation":"If a MatcherTree specifies prefix_match_map, the map must contain at least one entry; an empty prefix map gives the tree nothing to match and is rejected at construction. This enforces the non-empty map invariant before building the prefix trie.","triggerScenarios":"Constructing MatcherTree from a proto with hasPrefixMatchMap() true but matchMap.getMapCount() == 0 (map present but empty).","commonSituations":"Control plane emitting prefix routing config with all entries filtered out, or templated matcher config where prefix entries were not substituted.","solutions":["Populate prefix_match_map with at least one prefix -> on_match entry.","Validate the map is non-empty before sending the config from the management server.","If prefix matching is not needed, remove prefix_match_map and use exact_match_map."],"exampleFix":"// before\n{\"matcher_tree\": {\"input\": {...}, \"prefix_match_map\": {\"map\": {}}}}\n// after\n{\"matcher_tree\": {\"input\": {...}, \"prefix_match_map\": {\"map\": {\"/api/\": {\"matcher\": {...}}}}}}","handlingStrategy":"validation","validationCode":"if (treeProto.hasPrefixMatchMap() && treeProto.getPrefixMatchMap().getMapCount() == 0) {\n  throw new IllegalArgumentException(\"prefix_match_map present but empty\");\n}","typeGuard":"boolean hasNonEmptyPrefixMap(Matcher.MatcherTree proto) {\n  return !proto.hasPrefixMatchMap() || proto.getPrefixMatchMap().getMapCount() > 0;\n}","tryCatchPattern":"try {\n  matcherTree = new MatcherTree(proto, onNoMatch, validator);\n} catch (IllegalArgumentException e) {\n  logger.warn(\"empty prefix_match_map in config: \" + e.getMessage());\n  throw e;\n}","preventionTips":["Omit prefix_match_map rather than sending an empty map","Verify prefix entries survive config filtering","Lint xDS configs for empty map fields"],"tags":["xds","matcher","config-validation"],"backgroundTag":"empty-required-field","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}