{
  "id": "data/protobuf-unknown-enum-value",
  "signature": "Protobuf deserialization fails with 'Unknown enum value' when reading data with new enum values",
  "signature_zh": "Protobuf反序列化失败：读取包含新枚举值的数据时出现'未知枚举值'",
  "regex": "Unknown enum value.*for enum",
  "domain": "data",
  "category": "schema_error",
  "subcategory": null,
  "root_cause": "A new enum value was added to a Protobuf definition, but the reader's generated code is not updated, causing it to reject the unknown value instead of treating it as an unrecognized field.",
  "root_cause_type": "generic",
  "root_cause_zh": "Protobuf定义中添加了新的枚举值，但读取器的生成代码未更新，导致其拒绝未知值而非将其视为未识别字段。",
  "versions": [
    {
      "version": "Protocol Buffers 3.21+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "protoc 24.0+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "gRPC 1.60+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "The reader still runs old code; regenerating without redeployment has no effect.",
      "fail_rate": 1.0,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Enums in proto3 are already implicitly optional; making them explicit does not change how unknown values are handled.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Protobuf's generated code throws an exception during deserialization that cannot be easily caught without modifying the generated code itself.",
      "fail_rate": 0.65,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Update the reader to use the latest .proto file and regenerate the code. For Java: run `protoc --java_out=src/main/java myproto.proto` with the updated definition.",
      "success_rate": 1.0,
      "how": "Update the reader to use the latest .proto file and regenerate the code. For Java: run `protoc --java_out=src/main/java myproto.proto` with the updated definition.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use the `allow_alias` option in the .proto file to map the new enum value to an existing one as a temporary measure: `option allow_alias = true; NEW_VALUE = EXISTING_VALUE;`",
      "success_rate": 0.7,
      "how": "Use the `allow_alias` option in the .proto file to map the new enum value to an existing one as a temporary measure: `option allow_alias = true; NEW_VALUE = EXISTING_VALUE;`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Treat the field as `google.protobuf.Int32Value` wrapper to bypass enum validation, then convert the integer to the appropriate enum in application code.",
      "success_rate": 0.75,
      "how": "Treat the field as `google.protobuf.Int32Value` wrapper to bypass enum validation, then convert the integer to the appropriate enum in application code.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "更新读取器使用最新的.proto文件并重新生成代码。对于Java：使用更新后的定义运行`protoc --java_out=src/main/java myproto.proto`。",
    "在.proto文件中使用`allow_alias`选项将新枚举值临时映射到现有值：`option allow_alias = true; NEW_VALUE = EXISTING_VALUE;`",
    "将字段视为`google.protobuf.Int32Value`包装器以绕过枚举验证，然后在应用程序代码中将整数转换为适当的枚举。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://protobuf.dev/programming-guides/proto3/#enum",
  "official_doc_section": null,
  "error_code": "InvalidProtocolBufferException",
  "verification_tier": "ai_generated",
  "confidence": 0.86,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-12-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}