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.

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