{"record":{"id":"a7079a22c02fc999","repo":"grpc/grpc-java","slug":"failed-to-parse-metadata-key-s-type-s-error","errorCode":null,"errorMessage":"Failed to parse metadata key: %s, type: %s. Error: %s","messagePattern":"Failed to parse metadata key: (.+?), type: (.+?)\\. Error: (.+?)","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/MetadataRegistry.java","lineNumber":90,"sourceCode":"   * @param metadata the {@link Metadata} containing the fields to parse.\n   * @return an immutable map of parsed metadata.\n   * @throws ResourceInvalidException if parsing {@code typed_filter_metadata} fails.\n   */\n  public ImmutableMap<String, Object> parseMetadata(Metadata metadata)\n      throws ResourceInvalidException {\n    ImmutableMap.Builder<String, Object> parsedMetadata = ImmutableMap.builder();\n\n    // Process typed_filter_metadata\n    for (Map.Entry<String, Any> entry : metadata.getTypedFilterMetadataMap().entrySet()) {\n      String key = entry.getKey();\n      Any value = entry.getValue();\n      MetadataValueParser parser = findParser(value.getTypeUrl());\n      if (parser != null) {\n        try {\n          Object parsedValue = parser.parse(value);\n          parsedMetadata.put(key, parsedValue);\n        } catch (ResourceInvalidException e) {\n          throw new ResourceInvalidException(\n              String.format(\"Failed to parse metadata key: %s, type: %s. Error: %s\",\n                  key, value.getTypeUrl(), e.getMessage()), e);\n        }\n      }\n    }\n    // building once to reuse in the next loop\n    ImmutableMap<String, Object> intermediateParsedMetadata = parsedMetadata.build();\n\n    // Process filter_metadata for remaining keys\n    for (Map.Entry<String, Struct> entry : metadata.getFilterMetadataMap().entrySet()) {\n      String key = entry.getKey();\n      if (!intermediateParsedMetadata.containsKey(key)) {\n        Struct structValue = entry.getValue();\n        Object jsonValue = ProtobufJsonConverter.convertToJson(structValue);\n        parsedMetadata.put(key, jsonValue);\n      }\n    }\n","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/MetadataRegistry.java#L72-L108","documentation":"xDS node/filter metadata values are typed Any messages that must be parsed by a registered MetadataValueParser for their type_url. If the registered parser rejects the value (throws ResourceInvalidException), parseMetadata rethrows with the key, type_url, and underlying error so the offending metadata entry is identified.","triggerScenarios":"parsedFilterMetadata or parseLocalityLbEndpoints encounter metadata whose Any payload fails the parser for its type_url — e.g. a filter metadata Struct that does not match the expected proto schema, or an unparseable value for a well-known type.","commonSituations":"Control plane emitting filter metadata that doesn't match the typed extension schema (e.g. RBAC or Fault filter metadata fields with wrong types); version skew between envoy protos on server and client; typos in metadata keys expected to hold typed values.","solutions":["Read the nested 'Error:' message to find the parser's specific complaint, then fix that metadata value on the control plane","Ensure filter metadata matches the proto schema for the given type_url (validate with Envoy config dump)","Align envoy protos versions between management server and client dependencies","Remove or fix the offending metadata key in the LDS/CDS resource"],"exampleFix":"# before (typed filter metadata with wrong field type)\n\"com.foo\": {\"max_fault_percent\": \"fifty\"}\n# after\n\"com.foo\": {\"max_fault_percent\": 50}","handlingStrategy":"try-catch","validationCode":"// Validate typed metadata before attaching it to the resource:\nObject parsed = parserFor(typeUrl).parse(anyValue); // throws with schema detail if invalid","typeGuard":null,"tryCatchPattern":"try {\n  Map<String, ?> metadata = registry.parseFilterMetadata(metadataMap);\n} catch (ResourceInvalidException e) {\n  logger.warning(\"Metadata rejected: \" + e.getMessage()); // names key, type_url, and cause\n  // skip resource or strip the offending metadata key\n}","preventionTips":["Ensure filter metadata matches the proto schema for its type_url","Keep envoy protos versions identical on server and client","Validate metadata with Envoy config dump before ADS push"],"tags":["grpc","xds","metadata","protobuf"],"backgroundTag":"protobuf-unmarshal-failed","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"}