{"record":{"id":"3c1925211c6eb6c3","repo":"grpc/grpc-java","slug":"invalid-header-matcher-config-grpc-prefixed-he","errorCode":null,"errorMessage":"Invalid header matcher config: [grpc-] prefixed header name is not allowed.","messagePattern":"Invalid header matcher config: \\[grpc-\\] prefixed header name is not allowed\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/RbacFilter.java","lineNumber":325,"sourceCode":"    switch (proto.getRuleCase()) {\n      case PATH:\n        return PathMatcher.create(MatcherParser.parseStringMatcher(proto.getPath()));\n      case RULE_NOT_SET:\n      default:\n        throw new IllegalArgumentException(\n                \"Unknown path matcher rule type: \" + proto.getRuleCase());\n    }\n  }\n\n  private static RequestedServerNameMatcher parseRequestedServerNameMatcher(\n          io.envoyproxy.envoy.type.matcher.v3.StringMatcher proto) {\n    return RequestedServerNameMatcher.create(MatcherParser.parseStringMatcher(proto));\n  }\n\n  private static AuthHeaderMatcher parseHeaderMatcher(\n          io.envoyproxy.envoy.config.route.v3.HeaderMatcher proto) {\n    if (proto.getName().startsWith(\"grpc-\")) {\n      throw new IllegalArgumentException(\"Invalid header matcher config: [grpc-] prefixed \"\n          + \"header name is not allowed.\");\n    }\n    if (\":scheme\".equals(proto.getName())) {\n      throw new IllegalArgumentException(\"Invalid header matcher config: header name [:scheme] \"\n          + \"is not allowed.\");\n    }\n    return AuthHeaderMatcher.create(MatcherParser.parseHeaderMatcher(proto));\n  }\n\n  private static AuthenticatedMatcher parseAuthenticatedMatcher(\n          Principal.Authenticated proto) {\n    Matchers.StringMatcher matcher = MatcherParser.parseStringMatcher(proto.getPrincipalName());\n    return AuthenticatedMatcher.create(matcher);\n  }\n\n  private static DestinationPortMatcher createDestinationPortMatcher(int port) {\n    return DestinationPortMatcher.create(port);\n  }","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/RbacFilter.java#L307-L343","documentation":"This error is thrown by RbacFilter.parseHeaderMatcher when an xDS RBAC policy's header matcher specifies a header name starting with the reserved 'grpc-' prefix. The gRPC-internal 'grpc-*' metadata keys are reserved for the transport and must not be matched by RBAC rules, so the config is rejected at parse time with IllegalArgumentException.","triggerScenarios":"Parsing an xDS RBAC config (via parsePermission or parsePrincipal) whose v3 HeaderMatcher proto has name like 'grpc-timeout' or 'grpc-encoding'.","commonSituations":"Hand-written RBAC policy JSON/YAML copied from HTTP proxy configs that reference grpc-* headers; tools generating RBAC policies that include internal gRPC transport headers.","solutions":["Remove or rename the header matcher so it does not use a name starting with 'grpc-'","Match on a non-reserved application header instead (e.g. custom 'x-' headers)","Validate header names before submitting the xDS config to the management server"],"exampleFix":"// before\n{\"header\": {\"name\": \"grpc-timeout\", \"exactMatch\": \"10s\"}}\n// after\n{\"header\": {\"name\": \"x-request-tier\", \"exactMatch\": \"premium\"}}","handlingStrategy":"validation","validationCode":"if (headerMatcher.getName().startsWith(\"grpc-\")) {\n  throw new IllegalArgumentException(\"Reserved grpc- header name not allowed in RBAC matcher: \" + headerMatcher.getName());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never reference grpc-* headers in RBAC header matchers","Pre-validate all header matcher names against reserved prefixes before submitting xDS config","Keep RBAC policies generated from templates that whitelist allowed header names"],"tags":["grpc","xds","rbac","config-validation"],"backgroundTag":"invalid-config-value","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}