AvroFailure

Walker reached an enum value whose runtime symbol is not a member of the schema's declared symbol set. Schema-driven; no JSON analogue.

Input Array[Byte] didn't parse as an Avro binary record under the supplied schema. Surfaced only by the Avro | Array[Byte] overloads; when the caller passes a parsed org.apache.avro.generic.IndexedRecord directly this case cannot fire.

Codec refused at step. step is PathStep.Field("") at root-level decode failures on a path-empty prism. The wrapped Throwable is whatever the kindlings decoder threw — typically an AvroRuntimeException, an AvroTypeException, or a ClassCastException when the runtime payload doesn't line up with the schema.

Encoding a value back to Avro binary failed — the write-side counterpart of DecodeFailed. Surfaced by the fallible-build seam (T = Either[Chain[AvroFailure], Array[Byte]]), e.g. AvroBridge's from, when the codec's Any payload can't be written under the target schema. The wrapped Throwable is whatever apache-avro's GenericDatumWriter threw.

Index was outside [0, size) at step. size is the actual array length.

Input String didn't parse as Avro JSON wire format under the supplied schema. Surfaced only by the Avro | Array[Byte] | String overloads; record / bytes input cannot trigger this case. The wrapped Throwable is whatever apache-avro's JsonDecoder / GenericDatumReader threw — typically an AvroTypeException for shape mismatches, an IOException for malformed JSON, or an org.apache.avro.AvroRuntimeException for misc apache-avro complaints.

Parent wasn't a record at step (so the walker couldn't look up a field).

Parent wasn't an array at step (so the walker couldn't index).

Input bytes are not a Confluent-framed payload — shorter than the 5-byte header, or the magic byte isn't 0x00. Surfaced only by ConfluentWire.strip; reason names the specific check that refused.

Named field absent from its parent record at step (or absent map key).

Avro schema resolution refused — the read schema (what the bytes were written under) and the write schema (the resolve target) aren't compatible, so ResolvingDecoder can't translate the payload. The wrapped Throwable is whatever apache-avro's resolving GenericDatumReader threw (typically an AvroTypeException). Surfaced by AvroCodec.decodeResolvedRecord / decodeResolvedValue and the ConfluentWire resolving reader.

A Confluent-framed payload's writer schema (id schemaId) is not byte-identical to the reader schema — their Avro parsing-canonical-form fingerprints differ — so the direct byte walk would misread it. ConfluentWire.resolve / ConfluentWire.confluent GATE (refuse) here rather than hand back bytes that would misdecode. To TRANSLATE the drift instead of refusing, use the resolving reader (ConfluentWire.reader / ConfluentWire.resolving), which resolves writer→reader via Avro's ResolvingDecoder. Surfaced only by the gating surface.

The ConfluentWire.SchemaById hook threw while resolving schemaId to a writer schema — a registry miss, a network error, whatever the injected lookup raised. Surfaced only by ConfluentWire.resolve / ConfluentWire.confluent.

Walker reached a union value but none of the candidate branches matched the runtime type. branches is the list of schema-declared alternatives; step carries the PathStep.UnionBranch the walker was attempting to resolve. Schema-driven; no JSON analogue.

The byte-offset locator (AvroBinaryCursor) reached a PathStep kind it cannot resolve to a byte span — currently PathStep.Index: array elements sit inside length-prefixed blocks, so a single element's span is not graftable without rewriting the block framing. Surfaced only by sliceBytes / graftBytes; the decode-based surfaces (get / modify / at) keep supporting Index steps.