{
  "id": "data/avro-schema-field-type-mismatch",
  "signature": "Avro deserialization fails with 'Unexpected type for field' when reading old records with new schema",
  "signature_zh": "Avro反序列化失败：使用新模式读取旧记录时出现'字段类型意外'",
  "regex": "Unexpected type for field.*expected.*found",
  "domain": "data",
  "category": "schema_error",
  "subcategory": null,
  "root_cause": "An Avro schema evolution change modified a field's type (e.g., from 'int' to 'long' or from 'string' to 'bytes') without proper backward compatibility, causing deserialization of old records to fail.",
  "root_cause_type": "generic",
  "root_cause_zh": "Avro模式演化更改修改了字段类型（例如从'int'改为'long'或从'string'改为'bytes'），没有适当的向后兼容性，导致旧记录反序列化失败。",
  "versions": [
    {
      "version": "Apache Avro 1.11+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Confluent Schema Registry 7.5+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka Avro Deserializer 7.6+",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "This is a destructive operation that causes data loss and is often not feasible in production.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This does not fix the existing deserialization failure; old records still have the old type and cannot be read with the new schema.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This allows incompatible changes but does not help deserialize existing data; the error occurs at read time, not registration time.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Create a new schema version that uses a union type to accept both old and new types: change `\"type\": \"long\"` to `\"type\": [\"int\", \"long\"]`. Register this as a new version and update the reader to use it.",
      "success_rate": 0.85,
      "how": "Create a new schema version that uses a union type to accept both old and new types: change `\"type\": \"long\"` to `\"type\": [\"int\", \"long\"]`. Register this as a new version and update the reader to use it.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use a custom Avro datum reader that overrides the type resolution logic. For Java: extend `SpecificDatumReader` and override `resolveType` to handle the old type.",
      "success_rate": 0.75,
      "how": "Use a custom Avro datum reader that overrides the type resolution logic. For Java: extend `SpecificDatumReader` and override `resolveType` to handle the old type.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Reprocess old records through a converter that transforms them to the new schema, using a reader with the old schema and a writer with the new schema. Example with Apache Avro tools: `java -jar avro-tools-1.11.1.jar fromjson --schema-file old_schema.avsc old_data.json | java -jar avro-tools-1.11.1.jar tojson --schema-file new_schema.avsc > new_data.json`",
      "success_rate": 0.8,
      "how": "Reprocess old records through a converter that transforms them to the new schema, using a reader with the old schema and a writer with the new schema. Example with Apache Avro tools: `java -jar avro-tools-1.11.1.jar fromjson --schema-file old_schema.avsc old_data.json | java -jar avro-tools-1.11.1.jar tojson --schema-file new_schema.avsc > new_data.json`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "创建一个使用联合类型以接受新旧两种类型的新模式版本：将`\"type\": \"long\"`改为`\"type\": [\"int\", \"long\"]`。将其注册为新版本并更新读取器使用它。",
    "使用自定义Avro datum读取器覆盖类型解析逻辑。对于Java：扩展`SpecificDatumReader`并重写`resolveType`以处理旧类型。",
    "通过转换器重新处理旧记录，使用旧模式的读取器和新模式的写入器将其转换为新模式。使用Apache Avro工具的示例：`java -jar avro-tools-1.11.1.jar fromjson --schema-file old_schema.avsc old_data.json | java -jar avro-tools-1.11.1.jar tojson --schema-file new_schema.avsc > new_data.json`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://avro.apache.org/docs/1.11.1/spec.html#Schema+Evolution",
  "official_doc_section": null,
  "error_code": "AvroTypeException",
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.8,
  "resolvable": "true",
  "first_seen": "2024-01-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}