{
  "id": "data/avro-union-type-ordering-mismatch",
  "signature": "Avro deserialization fails: union type ordering mismatch between writer and reader schema",
  "signature_zh": "Avro 反序列化失败：写入器和读取器模式之间联合类型顺序不匹配",
  "regex": ".*union.*order.*mismatch.*|.*Avro.*union.*index.*",
  "domain": "data",
  "category": "schema_error",
  "subcategory": null,
  "root_cause": "Avro unions are order-sensitive; if the writer schema has union types in a different order than the reader schema (e.g., [\"null\", \"string\"] vs [\"string\", \"null\"]), deserialization fails with an index mismatch.",
  "root_cause_type": "generic",
  "root_cause_zh": "Avro 联合类型对顺序敏感；如果写入器模式的联合类型顺序与读取器模式不同（例如 [\"null\", \"string\"] 与 [\"string\", \"null\"]），反序列化会因索引不匹配而失败。",
  "versions": [
    {
      "version": "avro 1.11.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "confluent-kafka-avro 7.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "fastavro 1.9.4",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Defaults in Avro apply to the field itself, not to union type ordering. The index mismatch still occurs regardless of defaults.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Compatibility checks validate schema evolution rules but do not enforce union type ordering consistency across different schema versions.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure union types are always in alphabetical order: e.g., use [\"null\", \"string\"] not [\"string\", \"null\"]. In Avro schema definition: {\"name\": \"field\", \"type\": [\"null\", \"string\"]}. This is a best practice that prevents ordering issues.",
      "success_rate": 0.95,
      "how": "Ensure union types are always in alphabetical order: e.g., use [\"null\", \"string\"] not [\"string\", \"null\"]. In Avro schema definition: {\"name\": \"field\", \"type\": [\"null\", \"string\"]}. This is a best practice that prevents ordering issues.",
      "condition": "",
      "sources": []
    },
    {
      "action": "When reading, specify the writer schema explicitly: reader = fastavro.reader(fo, writer_schema=writer_schema). This bypasses the reader schema's union ordering.",
      "success_rate": 0.85,
      "how": "When reading, specify the writer schema explicitly: reader = fastavro.reader(fo, writer_schema=writer_schema). This bypasses the reader schema's union ordering.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Ensure union types are always in alphabetical order: e.g., use [\"null\", \"string\"] not [\"string\", \"null\"]. In Avro schema definition: {\"name\": \"field\", \"type\": [\"null\", \"string\"]}. This is a best practice that prevents ordering issues.",
    "When reading, specify the writer schema explicitly: reader = fastavro.reader(fo, writer_schema=writer_schema). This bypasses the reader schema's union ordering."
  ],
  "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.88,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2023-11-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}