# Avro serialization fails with SchemaRegistryException: incompatible schema version

- **ID:** `data/avro-schema-registry-serialization-version-mismatch`
- **Domain:** data
- **Category:** schema_error
- **Error Code:** `SchemaRegistryException`
- **Verification:** ai_generated
- **Fix Rate:** 82%

## Root Cause

The Confluent Schema Registry enforces compatibility rules (BACKWARD, FORWARD, FULL) and rejects schema evolution that violates the configured policy, often due to removing fields or changing types in a way that breaks existing consumers.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Confluent Platform 7.5 | active | — | — |
| Confluent Platform 7.6 | active | — | — |
| Apache Kafka 3.5 | active | — | — |
| Apache Kafka 3.6 | active | — | — |

## Workarounds

1. **Temporarily set compatibility to BACKWARD_TRANSITIVE for the subject, register the new schema, then revert to original policy: `curl -X PUT -H 'Content-Type: application/vnd.schemaregistry.v1+json' -d '{"compatibility": "BACKWARD_TRANSITIVE"}' https://registry:8081/config/subject-name`** (85% success)
   ```
   Temporarily set compatibility to BACKWARD_TRANSITIVE for the subject, register the new schema, then revert to original policy: `curl -X PUT -H 'Content-Type: application/vnd.schemaregistry.v1+json' -d '{"compatibility": "BACKWARD_TRANSITIVE"}' https://registry:8081/config/subject-name`
   ```
2. **Add the new field with a default value to maintain backward compatibility: `{"name": "new_field", "type": "string", "default": ""}`** (90% success)
   ```
   Add the new field with a default value to maintain backward compatibility: `{"name": "new_field", "type": "string", "default": ""}`
   ```
3. **Use FULL_TRANSITIVE compatibility and register a new version that adds fields with defaults and removes no fields** (88% success)
   ```
   Use FULL_TRANSITIVE compatibility and register a new version that adds fields with defaults and removes no fields
   ```

## Dead Ends

- **** — Schema Registry does not allow deletion of schemas that have been used; you must use soft delete or wait for the cleanup policy. (85% fail)
- **** — This creates a new subject that existing consumers are not subscribed to, breaking data flow and requiring manual topic reconfiguration. (70% fail)
- **** — Disabling compatibility entirely allows any schema change, which can silently break downstream consumers and cause production incidents. (60% fail)