{
  "id": "data/avro-schema-registry-backward-transitive-failure",
  "signature": "SchemaRegistryException: schema is not backward-compatible — field 'phone_number' added without default in version 3",
  "signature_zh": "SchemaRegistryException: 模式不向后兼容——版本3中添加了没有默认值的字段'phone_number'",
  "regex": "SchemaRegistryException.*not backward-compatible|backward compatibility.*field.*without default",
  "domain": "data",
  "category": "schema_error",
  "subcategory": null,
  "root_cause": "Avro schema evolution requires new fields to have default values when backward compatibility is enforced; adding a field without a default breaks consumers that read old data.",
  "root_cause_type": "generic",
  "root_cause_zh": "Avro模式演化要求在启用向后兼容性时新字段必须有默认值；添加没有默认值的字段会破坏读取旧数据的消费者。",
  "versions": [
    {
      "version": "Confluent Schema Registry 7.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Apache Avro 1.11.3",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Schema Registry enforces compatibility globally; deleting a version may break existing producers/consumers and cause data loss if they reference that version ID.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Disabling compatibility entirely removes all checks, allowing any schema change, which can cause silent data corruption for downstream consumers that expect a specific structure.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The producer will fail to serialize because the schema must match the registered schema exactly (Avro writer schema validation).",
      "fail_rate": 1.0,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Update the Avro schema to add the field with a default value: `{\"name\": \"phone_number\", \"type\": [\"null\", \"string\"], \"default\": null}` and register as version 4 with backward compatibility",
      "success_rate": 0.95,
      "how": "Update the Avro schema to add the field with a default value: `{\"name\": \"phone_number\", \"type\": [\"null\", \"string\"], \"default\": null}` and register as version 4 with backward compatibility",
      "condition": "",
      "sources": []
    },
    {
      "action": "If the field must be required, change compatibility to FORWARD_TRANSITIVE, register the new schema, then update consumers to handle the new field before switching back to BACKWARD",
      "success_rate": 0.85,
      "how": "If the field must be required, change compatibility to FORWARD_TRANSITIVE, register the new schema, then update consumers to handle the new field before switching back to BACKWARD",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use Schema Registry REST API to set compatibility to BACKWARD_TRANSITIVE on the subject, then re-register: `curl -X PUT -H \"Content-Type: application/json\" --data '{\"compatibility\": \"BACKWARD_TRANSITIVE\"}' http://localhost:8081/config/<subject>`",
      "success_rate": 0.9,
      "how": "Use Schema Registry REST API to set compatibility to BACKWARD_TRANSITIVE on the subject, then re-register: `curl -X PUT -H \"Content-Type: application/json\" --data '{\"compatibility\": \"BACKWARD_TRANSITIVE\"}' http://localhost:8081/config/<subject>`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Update the Avro schema to add the field with a default value: `{\"name\": \"phone_number\", \"type\": [\"null\", \"string\"], \"default\": null}` and register as version 4 with backward compatibility",
    "If the field must be required, change compatibility to FORWARD_TRANSITIVE, register the new schema, then update consumers to handle the new field before switching back to BACKWARD",
    "Use Schema Registry REST API to set compatibility to BACKWARD_TRANSITIVE on the subject, then re-register: `curl -X PUT -H \"Content-Type: application/json\" --data '{\"compatibility\": \"BACKWARD_TRANSITIVE\"}' http://localhost:8081/config/<subject>`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.confluent.io/platform/current/schema-registry/avro.html",
  "official_doc_section": null,
  "error_code": "42201",
  "verification_tier": "ai_generated",
  "confidence": 0.92,
  "fix_success_rate": 0.9,
  "resolvable": "true",
  "first_seen": "2023-11-20",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}