Recursive tuples

[trustedtomato]

As of right now, recursive tuples such as

const y = z.lazy((): any => z.tuple([y, y]).or(z.string()))
y.parse(["a", ["b", "c"]])
// infinite recursion

cause infinite recursion. However, recursive arrays have no such problem:

const y = z.lazy((): any => z.array(y).or(z.string()))
y.parse(["a", ["b", "c"]])
// works

Would it be possible to also enable creating recursive tuples?

[dosubot]

Hi @trustedtomato! I'm Dosu and I’m helping the zod team.

Recursive tuples with z.lazy and z.tuple in Zod currently cause infinite recursion because tuple schemas are eagerly resolved for all elements at once, which repeatedly invokes the lazy schema and leads to an infinite loop. In contrast, recursive arrays work because array validation is done element by element, allowing lazy evaluation to break the cycle as needed. This is a technical challenge tied to how tuples are implemented in Zod and is not unique to Zod—it's also related to how TypeScript handles recursive types [issue #577] [issue #1649].

A common workaround is to wrap the recursive part with .or(z.string()) or a similar union to provide a base case, which can help avoid infinite recursion in some scenarios [issue #1649]. Fully supporting recursive tuples would require significant changes to how tuple validation is implemented in Zod.

If this answers your question, feel free to close the issue! Let me know if you need more details or examples.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[trustedtomato]

Replying to the bot: Tried the following code, but it still doesn't work.

const y = z.lazy((): any => z.string().or(z.lazy(() => z.tuple([y, y]))))
y.parse(["a", ["b", "c"]])

[dosubot]

This still results in infinite recursion because Zod's tuple schemas are eagerly resolved for all elements at once—even when wrapped in z.lazy or a union—so the recursive reference keeps expanding without a stopping point. In contrast, arrays validate elements one at a time, which allows lazy evaluation to break the cycle and makes recursive arrays work as expected. This is a fundamental technical challenge with how tuple validation is implemented in Zod and is also influenced by TypeScript's type system. There are no alternative workarounds or recent changes that address this for tuples; supporting recursive tuples would require significant changes to Zod's internals. More details and examples are in issue #577 and issue #1649. If you have a specific recursive tuple use case, let me know—otherwise, using recursive arrays or objects is the recommended approach for now. If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[trustedtomato]

Replying to the bot: Unfortunately I cannot use neither objects nor arrays, because the format I'm receiving uses an array which needs to have specific types at specific indices in the array.

[dosubot]

Zod doesn't currently support recursive tuples because tuple validation eagerly resolves all elements at once, which causes infinite recursion when using z.lazy with z.tuple—even if you use a union with a base case. This is a technical challenge in both Zod and TypeScript, and there are no workarounds or recent changes that address this for tuples specifically. The only partial workaround is to use a union with a base case (like .or(z.string())), but this doesn't solve the eager evaluation problem and only works in limited scenarios, as discussed in issue #1649.

If you can share a concrete example of your tuple structure and the recursion pattern, I can help brainstorm a custom validation function or Zod refinement that might fit your needs. Otherwise, recursive tuple validation remains an unsolved challenge in Zod. If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[trustedtomato]

Replying to the bot: Can you try to work on the code I provided?

const y = z.lazy((): any => z.string().or(z.lazy(() => z.tuple([y, y]))))
y.parse(["a", ["b", "c"]])

Note that in my specific use case I also need to be able to run z.toJSONSchema on the resulting ZodType.

[dosubot]

Your code for recursive tuples doesn't work in Zod because tuple schemas are eagerly resolved for all elements, so the recursion never gets a chance to short-circuit—this leads to infinite recursion at both validation and type inference time. This is a fundamental technical challenge in Zod and TypeScript, and it's why recursive arrays work (they validate elements one at a time) but tuples do not [issue #577] [issue #1649].

There's currently no workaround or recent change in Zod 4 that enables recursive tuples or allows generating JSON Schema from them. The JSON Schema generator also eagerly traverses tuple elements, so it will recurse infinitely for a recursive tuple schema [issue #1649].

If you absolutely need tuple-like validation and JSON Schema output for recursive data, the only options are to restructure your data (if possible) or implement a custom validation function outside of Zod. If you have a specific edge case or workaround in mind, let me know! Otherwise, recursive tuple validation and JSON Schema generation remain unsolved in Zod. If this answers your question, please close the issue.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[trustedtomato]

I just checked zod@3, the initial code seems to work there. Seems like this a regression in zod@4.

[dosubot]

You're right—recursive tuples with z.lazy worked in Zod 3, but not in Zod 4. This is a regression caused by a change in how Zod 4 eagerly traverses schema internals (including tuple elements) at construction time, which triggers immediate infinite recursion for recursive tuples. In Zod 3, the lazy getter was only called at parse time, so recursive tuples could work as expected. There’s no documentation or changelog entry describing this change, so it appears to be an unintended side effect rather than an intentional breaking change.

Recursive tuple support is a known technical challenge and is not currently supported in Zod 4. There’s no workaround at this time, and attempts to generate JSON Schema from recursive tuples will also result in infinite recursion. For more background, see issue #577 and issue #1649.

Tagging @colinhacks for visibility in case there are plans to address this regression. If this answers your question, please close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[colinhacks]

Yep should be fixable. Open to a PR if you want to investigate, otherwise I'll look into this in the next few days.

[NathanKneT]

Hi @colinhacks

I've submitted a PR (#5094) that fixes this regression. The issue was caused by unsafe property access in the $ZodLazy and $ZodReadonly constructors during circular reference

fix:

• Added optional chaining (?.) to prevent accessing _zod properties on undefined objects
• Minimal change that maintains performance and backward compatibility
• Test suite to prevent future regressions

testing:

• ✅ All existing tests pass
• ✅ All examples from this issue now work correctly
• ✅ Both schema creation and parsing work as expected

The recursive tuple patterns mentioned by @trustedtomato now work exactly like they did in v3