# Avro deserialization fails: union field expects a specific branch but got null

- **ID:** `data/avro-record-schema-union-mismatch`
- **Domain:** data
- **Category:** type_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Apache Avro 1.11.1 | active | — | — |
| Confluent Avro Serializer 7.4 | active | — | — |
| Python avro 1.11.0 | active | — | — |

## Workarounds

1. **Update the Avro schema to include null as the first branch in the union: change '["string"]' to '["null", "string"]' and set default to null.** (90% success)
   ```
   Update the Avro schema to include null as the first branch in the union: change '["string"]' to '["null", "string"]' and set default to null.
   ```
2. **Use a custom deserializer that gracefully handles null values by mapping them to a default string: if val is None: val = 'default'.** (80% success)
   ```
   Use a custom deserializer that gracefully handles null values by mapping them to a default string: if val is None: val = 'default'.
   ```

## Dead Ends

- **Adding a default value of null to the union field in the schema** — The default value applies during schema evolution but does not fix existing data that has mismatched branches. (70% fail)
- **Changing the entire field type to a single type (e.g., string) to avoid unions** — This breaks compatibility with existing data and requires re-encoding all messages. (90% fail)