{
  "id": "data/avro-record-schema-union-mismatch",
  "signature": "Avro deserialization fails: union field expects a specific branch but got null",
  "signature_zh": "Avro反序列化失败：联合字段期望特定分支但收到null",
  "regex": "union.*expects|Avro.*union.*null|branch mismatch",
  "domain": "data",
  "category": "type_error",
  "subcategory": null,
  "root_cause": "An Avro schema defines a union field (e.g., [\"null\", \"string\"]) but the data contains a null value when the schema expects a non-null branch, or vice versa, due to schema evolution or data corruption.",
  "root_cause_type": "generic",
  "root_cause_zh": "Avro模式定义了一个联合字段（例如，[\"null\", \"string\"]），但由于模式演变或数据损坏，数据包含null值而模式期望非null分支，或相反。",
  "versions": [
    {
      "version": "Apache Avro 1.11.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Confluent Avro Serializer 7.4",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python avro 1.11.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Adding a default value of null to the union field in the schema",
      "why_fails": "The default value applies during schema evolution but does not fix existing data that has mismatched branches.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Changing the entire field type to a single type (e.g., string) to avoid unions",
      "why_fails": "This breaks compatibility with existing data and requires re-encoding all messages.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Update the Avro schema to include null as the first branch in the union: change '[\"string\"]' to '[\"null\", \"string\"]' and set default to null.",
      "success_rate": 0.9,
      "how": "Update the Avro schema to include null as the first branch in the union: change '[\"string\"]' to '[\"null\", \"string\"]' and set default to null.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a custom deserializer that gracefully handles null values by mapping them to a default string: if val is None: val = 'default'.",
      "success_rate": 0.8,
      "how": "Use a custom deserializer that gracefully handles null values by mapping them to a default string: if val is None: val = 'default'.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "更新Avro模式，将null作为联合的第一个分支：将'[\"string\"]'改为'[\"null\", \"string\"]'并将默认值设为null。",
    "使用自定义反序列化器优雅地处理null值，将其映射为默认字符串：if val is None: val = 'default'。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://avro.apache.org/docs/current/spec.html#Unions",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.85,
  "resolvable": "true",
  "first_seen": "2023-02-14",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}