# Avro deserialization fails: union type ordering mismatch between writer and reader schema

- **ID:** `data/avro-union-type-ordering-mismatch`
- **Domain:** data
- **Category:** schema_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

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

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| avro 1.11.3 | active | — | — |
| confluent-kafka-avro 7.5.0 | active | — | — |
| fastavro 1.9.4 | active | — | — |

## Workarounds

1. **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.** (95% success)
   ```
   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.
   ```
2. **When reading, specify the writer schema explicitly: reader = fastavro.reader(fo, writer_schema=writer_schema). This bypasses the reader schema's union ordering.** (85% success)
   ```
   When reading, specify the writer schema explicitly: reader = fastavro.reader(fo, writer_schema=writer_schema). This bypasses the reader schema's union ordering.
   ```

## Dead Ends

- **** — Defaults in Avro apply to the field itself, not to union type ordering. The index mismatch still occurs regardless of defaults. (80% fail)
- **** — Compatibility checks validate schema evolution rules but do not enforce union type ordering consistency across different schema versions. (70% fail)