Repository navigation
fix: union containing z.undefined() should be optional-in for object keys - #6044
sapirbaruch wants to merge 1 commit into
Conversation
When a z.union() has z.undefined() as one of its options, the union
accepts undefined as a valid value. In object schemas, z.object checks
el._zod.optin === "optional" to decide whether a missing key is allowed.
Before this fix, a union containing z.undefined() did not propagate the
optin/optout flags, so { choices: z.union([z.never(), z.array(z.never()), z.undefined()]) }
would throw "expected nonoptional, received undefined" for missing keys
even though the union can parse undefined just fine.
The fix: in the $ZodUnion constructor, extend the optin/optout lazy
check to also match options whose _zod.values set includes undefined
(which is how z.undefined() signals it accepts undefined).
Fixes colinhacks#5993
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — Restores 4.3.x optional-in behavior for unions containing z.undefined() as an object key, fixing the regression introduced in 4.4.0.
packages/zod/src/v4/core/schemas.ts— Addso._zod.values?.has(undefined)to$ZodUnion's lazyoptin/optoutcomputation so unions with az.undefined()member correctly propagate the optional flag.packages/zod/src/v4/classic/tests/never-union-object.test.ts— New regression test covering the exact discord.js scenario from #5993.packages/zod/src/v4/classic/tests/optional.test.ts— Updates snapshot and assertions to reflect the restored behavior.
Kimi K2 | 𝕏
wahajahmed010
left a comment
There was a problem hiding this comment.
Great catch and clean fix, @sapirbaruch! The root cause analysis is spot-on — PR #5661 cleaned up optin/optout from $ZodUndefined, but the union propagation needed to catch undefined through the values set instead. The fix is conservative and correct.
What I like:
- Clear reproduction path from discord.js downstream
- The optional chaining on _zod.values handles schemas that do not define a values set (e.g., ZodString, ZodNumber) gracefully
- Test coverage is thorough — covers all 4 states (explicit undefined, empty array, populated array, missing key)
One thought for completeness:
The tests cover a single-depth union in an object. Worth also adding a nested union test: a z.union inside another z.union with z.undefined(). The lazy chain should propagate optin correctly, but locking it in with a test would prevent regression. Not a blocker.
Excellent first contribution! 🦌
|
Closing this — the 4.4.0 behavior is intentional. Append |

Ran into this via the discord.js bug report in #5993 — after digging in I traced it to a change in 4.4.0 (commit b6066b3, PR #5661) that stripped
optin/optoutoff$ZodUndefined.The problem:
z.objectdecides whether a missing key is valid by checkingel._zod.optin === "optional". Before 4.4,z.undefined()set that flag, so a union like:was treated as optional-in and a missing key would silently coerce to
undefined(which the union accepts). After the change, neitherz.undefined()nor the union propagate that flag, so the object bails early with"expected nonoptional"before the schema even runs.The fix:
In
$ZodUnion's lazyoptin/optoutcomputation, also check whether any option's_zod.valuesset includesundefined.z.undefined()hasvalues = new Set([undefined]), so a union with az.undefined()member now correctly inherits the optional-in/out behavior.This is intentionally conservative: the new check only fires when a member's static value set contains
undefined, which is exactly when the union will accept a missing key.Repro:
The updated snapshot in
optional.test.ts(line ~144) reflects the corrected behavior: only thez.undefined()standalone field still requires an explicit key; a union containingz.undefined()does not.Refs #5993.