parser failed on avro schema with union types agent couldn't parse schema error

TL;DR

Union types need union-aware handling: parse the Avro schema with a real Avro library rather than a hand-rolled JSON walker, represent unions explicitly in the agent's internal model as a list of branch types, and resolve the null branch as the default case. Agents that flatten unions into a single type will fail or misread every nullable field, since nullable in Avro is a union with null.

parser failed on avro schema with union types agent couldn't parse schema error

Use this when

• The check or run fails with this symptom: the agent's schema parsing breaks on Avro union types.
• You are working on an agent that cannot parse an Avro schema containing union types 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

• An Avro compatibility rejection at the registry, which is an evolution problem rather than a parsing problem instead.
• The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

Steps

1. Load the schema with the Avro library's own parser and confirm it accepts the document. Verify: the library parses the schema cleanly
2. Find where the agent's code assumes a field type is a plain string, since union types arrive as a list. Verify: the single-type assumptions are located
3. Update the internal model so a field type can be a single type or a list of branch types, with the record and array branches recursed into. Verify: the model represents unions explicitly
4. Add handling for the common two-branch pattern of a type plus null, including which branch supplies the default. Verify: nullable unions resolve with their defaults
5. Parse a set of real schemas from the registry, including nested unions, and confirm the agent produces the expected field model for each. Verify: the real schema set parses into correct models

Variant phrasings

parser failed avro schema union types agent

The verbatim Avro-union phrasing.

avro union null branch parse schema agent

The null-branch phrasing for nullable fields.

agent cannot parse avro schema nested unions

The nested-union phrasing for records inside unions.

Compatibility: Avro schemas with union types parsed by agents using fastavro or the Avro Python library

Why it happens

Avro encodes optionality and polymorphism as unions, so unions appear in nearly every real schema, often nested inside records and arrays. A parser written against simple schemas meets a union early and fails because its type model has no place to put a list of types.

Edge cases / pitfalls

• Unions cannot contain duplicate types or more than one unnamed branch of the same kind; validate that before blaming the agent.
• Keep the raw schema beside the parsed model so branch decisions stay auditable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstS-Y-qysk0LG4zho7KJulQ