schema evolution failed error: avro schema compatibility check failure

TL;DR

An Avro compatibility failure names the exact rule broken: read the registry's compatibility error, diff the new schema against the latest registered version, and change the evolution to a compatible form, such as adding fields only with defaults or keeping field names and types stable. Registering with compatibility disabled trades one error for consumer breakage later.

schema evolution failed error: avro schema compatibility check failure

Use this when

• The check or run fails with this symptom: the registry rejects the new Avro schema as incompatible with the previous version.
• You are working on an Avro schema failing its registry compatibility check and the failure repeats on the same data or configuration.
• You need the failing rows, rule, or stage isolated before changing thresholds or code.

Not for this skill when

• A JSON schema contract failure, which follows different evolution rules instead.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Capture the registry's compatibility message, which names the rule and the field that broke it. Verify: the broken rule and field are recorded
2. Diff the proposed schema against the latest registered version field by field. Verify: all differences are listed and classified
3. Check the subject's compatibility mode, since a change legal under BACKWARD can fail under FULL. Verify: the active mode and its implications are known
4. Rewrite the change compatibly: add new fields with defaults, avoid type promotions the mode forbids, and never reuse a removed field name with a new meaning. Verify: the revised schema follows the mode's rules
5. Re-run the registry compatibility test before registering, then register and produce a test record consumers can read. Verify: the test passes and a consumer reads the new record

Variant phrasings

avro schema compatibility check failure

The verbatim compatibility phrasing.

schema registry incompatible change avro default

The defaults phrasing for adding fields compatibly.

avro evolution breaking change reader schema

The reader-impact phrasing for breaking evolutions.

Compatibility: Avro schema registry with BACKWARD, FORWARD, and FULL compatibility modes

Why it happens

Avro readers resolve writer schemas against their own, so removing fields without defaults, changing types, or renaming fields breaks consumers compiled against earlier versions. The registry enforces the subject's compatibility mode at registration time, which is why the failure appears before any data flows.

Edge cases / pitfalls

• Test compatibility in CI on every schema change, not at deploy time when the registry rejects it.
• Enum additions can also break strict readers. Treat enum changes as compatibility events.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JrkBxdYjWPlwnNOVmVRHKA