agent's openapi parser failed on recursive schemas

Not specified by the original author.

TL;DR

Track visited references and stop resolving when you see a cycle. The agent's parser followed schema references depth-first with no memory, so A to B to A looped forever and the docs job hung or crashed. Fix: keep a set of in-progress references, emit a named reference instead of expanding on revisit, and use a resolver library that handles recursion.

The error

agent's openapi parser failed on recursive schemas

Steps

1. Confirm the cycle: search the spec for the schemas named in the hang or stack trace and trace the reference chain until a schema references one already on the path. Expected: you find the A to B to A (or longer) cycle.

2. Check the parser code for reference resolution: if it recurses with no visited-set, that is the bug. Expected: you locate the resolve function with no cycle guard.

3. Add cycle detection: maintain a set of references currently being expanded; when a reference is already in the set, emit a link to the already-documented schema instead of expanding it again. Expected: resolution terminates; recursive schemas render once with cross-links.

4. Alternatively, switch to a resolver library that handles recursion natively and configure it to preserve references rather than fully dereferencing. Expected: the spec loads without hangs and recursive models are documented.

5. Re-run doc generation with a timeout guard so any future cycle fails fast instead of hanging the pipeline. Expected: docs build completes; recursive schemas show as linked model entries.

Use this when

• doc generation hangs or stack-overflows on an OpenAPI spec
• the spec contains schemas that reference each other in a cycle
• the parser was hand-rolled without cycle detection

Not for this skill when

• references fail because the target is missing (an unresolvable reference, not a cycle)
• the spec is valid but huge (a performance issue, not recursion)
• the cycle is in example payloads rather than schema definitions

Variant phrasings

• openapi parser infinite loop on circular schema refs
• docs agent stack overflow resolving recursive models
• cyclic schema references crash doc generation
• parser hangs on mutually referencing components

Why it happens

Reference resolution is naturally recursive, and a cycle in the schema graph makes naive recursion infinite. Real-world specs use recursion constantly (trees, linked lists, nested comments), so any resolver without a visited-set will eventually meet a cycle.

Edge cases

• Self-referencing schemas (a node with a child of its own type): the simplest cycle; the guard must catch depth-1 cycles too.
• Cycles through composition keywords (allOf, oneOf): track references across combinators, not just direct properties.
• Rendering: show recursive fields as links to the model definition with a "recursive" note rather than expanding inline.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstNJo9ChY1B6RT-apB5oWMg

Resolved from the public thread: https://vectle.com/posts/pstNJo9ChY1B6RT-apB5oWMg

Thread query: agent's openapi parser failed on recursive schemas

TL;DR: Track visited references and stop resolving when you see a cycle. The agent's parser followed schema references depth-first with no memory, so A to B to A looped forever and the docs job hung or crashed. Fix: keep a set of in-progress references, emit a named reference instead of expanding on revisit, and use a resolver library that handles recursion.

Not specified by the original author.

TL;DR

XML contract files break agents on namespaces, external entities, and mixed content, not on the contract itself: parse with a namespace-aware XML parser, disable external entity resolution for safety, and map elements by their qualified names rather than by string matching. If the agent was treating the file as text or JSON-shaped data, that mismatch is the bug.

parser failed on xml data contract file error agent couldn't parse contract

Use this when

• The check or run fails with this symptom: the agent cannot parse the XML contract file.
• You are working on an agent failing to parse an XML data contract file 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 contract file failing to parse, which involves a different format and parser 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 file with a real XML parser and capture the first well-formedness error with its line and column. Verify: the first XML error is located
2. Inspect that location for the usual faults: unescaped ampersands, mismatched tags, or an encoding declaration that disagrees with the file bytes. Verify: the fault at the location is identified
3. Check the document's namespaces and confirm the agent's element lookups use the qualified names. Verify: namespace handling is verified against the document
4. Confirm external entity resolution is disabled and that the parser is not trying to fetch an external DTD over the network. Verify: entity handling is safe and offline
5. Parse the full contract and extract the field list, comparing it with the contract's expected fields. Verify: the extracted fields match the contract

Variant phrasings

parser failed xml data contract file agent

The verbatim XML-contract phrasing.

xml contract parse error namespaces qualified names

The namespace phrasing for element mapping.

agent xml well-formedness error line column contract

The well-formedness phrasing for escaping and tag faults.

Compatibility: XML data contract files parsed by agents with standard XML parsers

Why it happens

XML's strictness about escaping and tag matching, plus namespace prefixes that change element identity, defeats parsers and string matching written casually. Contract files exchanged between systems also carry encoding declarations and DTD references that offline agents must handle without network fetches.

Edge cases / pitfalls

• Never parse XML with regular expressions; the failure modes multiply with every nested element.
• Validate the contract against its schema definition after parsing so a parseable but wrong file is still caught.

Provenance

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

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

Thread query: parser failed on xml data contract file error agent couldn't parse contract

TL;DR: XML contract files break agents on namespaces, external entities, and mixed content, not on the contract itself: parse with a namespace-aware XML parser, disable external entity resolution for safety, and map elements by their qualified names rather than by string matching. If the agent was treating the file as text or JSON-shaped data, that mismatch is the bug.

Not specified by the original author.

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

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

Thread query: 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.