René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Stack overflow in propagateRemoteRefs when a self-recursive external schema is composed via allOf more than once","articleBody":"### What happened\n\nGeneration overflows the goroutine stack inside `propagateRemoteRefs` when a **self-recursive schema in an external file** is composed via `allOf` from **more than one place**.\n\nComposing it once works. Composing it twice crashes. Nothing references back into the main document — the recursion is entirely inside the external file.\n\n### Reproduction\n\n`common.yaml` — a self-recursive schema, no reference to the main document:\n\n```yaml\nopenapi: 3.0.3\ninfo: {title: common, version: \"1.0\"}\npaths: {}\ncomponents:\n  schemas:\n    Tree:\n      type: object\n      properties:\n        name: { type: string }\n        kids:\n          type: array\n          items: { $ref: '#/components/schemas/Tree' }\n```\n\n`main.yaml`:\n\n```yaml\nopenapi: 3.0.3\ninfo: {title: main, version: \"1.0\"}\npaths: {}\ncomponents:\n  schemas:\n    A:\n      allOf:\n        - $ref: './common.yaml#/components/schemas/Tree'\n        - type: object\n          properties: { extra: { type: string } }\n    # Remove B and generation succeeds. Add it back and the stack overflows.\n    B:\n      allOf:\n        - $ref: './common.yaml#/components/schemas/Tree'\n        - type: object\n          properties: { other: { type: string } }\n```\n\n`config.yaml`:\n\n```yaml\npackage: repro\ngenerate:\n  models: true\noutput-options:\n  skip-prune: true\nimport-mapping:\n  ./common.yaml: github.com/example/common\n```\n\n```console\n$ oapi-codegen -config config.yaml main.yaml\nruntime: goroutine stack exceeds 1000000000-byte limit\nfatal error: stack overflow\n```\n\nThe trace is ~90 repeating `codegen.propagateRemoteRefs` frames entered once from `codegen.valueWithPropagatedRef`.\n\n### Root cause\n\n`valueWithPropagatedRef` (`pkg/codegen/merge_schemas.go`) takes a **shallow** copy of the referenced schema:\n\n```go\nschema := *ref.Value\n```\n\n`Properties`, `Items` and the `*SchemaRef` values inside are therefore the *same objects* as in the loaded document. `propagateRemoteRefs` then rewrites local refs in place, mutating the shared document permanently.\n\nIts only termination rule is the `#` test:\n\n```go\nif len(value.Ref) > 0 && value.Ref[0] == '#' {\n    value.Ref = remoteComponent + value.Ref   // rewrite, do not descend\n} else if value.Value != nil {\n    propagateRemoteRefs(remoteComponent, value.Value)   // descend\n}\n```\n\nStopping at a local `$ref` is what makes a self-recursive external schema safe — on the first pass. But **the rewrite destroys the condition that stopped it**: afterwards the ref reads `./common.yaml#/components/schemas/Tree`, which no longer starts with `#`. The next walk over the same nodes falls through to `else if value.Value != nil` and descends into the resolved schema, i.e. straight around the cycle, forever.\n\nSo the rewrite is not idempotent, and because it mutates shared state the failure is order-dependent: whichever component the alphabetical iteration reaches first performs the rewrite, and the next one to touch the same external schema crashes. In a real multi-file setup — shared types in `common.yaml`, composed via `allOf` from several components — this will look intermittent and sensitive to unrelated schema renames.\n\n### Scope\n\nReproduced on `main` @ `2679cec6`. Independent of #2542 / #2543: it is a different phase (rewriting `$ref` strings before any Go schema is generated) and a different code path, and it reproduces with none of that work in the tree.\n\n### Possible fixes\n\n1. **Make the rewrite idempotent** — also stop when the ref is already qualified with this `remoteComponent`. One line, fixes this repro.\n2. **Guard the walk** with a `seen map[*openapi3.Schema]bool`. Covers shapes the prefix test might miss.\n3. **Stop mutating shared state** — deep-copy the schema before rewriting. Addresses the order-dependence rather than just this symptom, at the cost of a larger change.\n\n(1) or (2) is a contained fix; (3) is the principled one, since the current behaviour means generating component `A` can change what component `B` generates.\n\n---\n\n\u003csub>🤖 Investigated and drafted with [Claude Code](https://claude.com/claude-code); the repro above was verified against `main` @ `2679cec6` (v2.8.0).\u003c/sub>\n","author":{"url":"https://github.com/mromaszewicz","@type":"Person","name":"mromaszewicz"},"datePublished":"2026-09-17T05:21:04Z","url":"https://github.com/oapi-codegen/oapi-codegen/issues/2557"}