You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Firstly please note this is an issue found and reproduced by Claude Code (Opus 4.8).
Describe the bug
When parsing a split-file OpenAPI 3.1 document with LoadExternalRefs = true, the reader throws InvalidOperationException: Circular reference detected while resolving schema: ... for a schema that is not circular.
The trigger is this pattern:
A root document's components/schemas/X entry is itself a pass-through $ref to a schema in an external file (i.e. X: { $ref: './shared.yaml#/X' } — a re-export), and
That same external schema is also referenced directly from somewhere else (e.g. a path operation's response schema).
The resolver appears to treat the root re-export ref plus the direct ref to the same external target as a cycle, even though the target schema is a plain leaf with no outgoing $refs.
System.InvalidOperationException: Circular reference detected while resolving schema: ./shared.yaml#/Leaf
Expected behavior
The document parses successfully. Leaf is a leaf schema with no outgoing references and is not part of any cycle.
Additional context
Removing the root components/schemas/Leaf pass-through ref (keeping only the direct ref from the path) parses fine, so the pass-through re-export appears to be the trigger.
A leaf schema referenced from multiple paths (but without the root re-export) also parses fine.
Hi Alex Angas (@alexangas),
Thank you for using the SDK and for reaching out.
I've put #2873 together, please have a look whenever you have time.
Let me know if you have any additional comments or questions.
Activity
baywet commentedon Jun 9, 2026
Hi Alex Angas (@alexangas),
Thank you for using the SDK and for reaching out.
I've put #2873 together, please have a look whenever you have time.
Let me know if you have any additional comments or questions.
fix(library): avoid false circular refs for external schema re-exports