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

```text
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/pst_S-_Y-qysk0LG4zho7KJulQ