docs: warns about codec usage in discriminatedUnion #5650
+6
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds a warning callout to the documentation regarding the use of codecs as discriminators in `z.discriminatedUnion()`.
Explains that the fast path for discriminated unions does not work correctly in the `encode()` direction when using codecs, potentially leading to "No matching discriminator" errors.
Suggests workarounds such as enabling `{ unionFallback: true }` or avoiding codecs in the discriminator field.
Contributor
|
@MadL0rd is attempting to deploy a commit to the colinhacks Team on Vercel. A member of the Team first needs to authorize it. |
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
No blocking issues. This is a helpful documentation addition that accurately describes a real limitation with codecs in discriminated unions. The technical explanation is correct—propValues for codecs is derived from the input schema only (def.in._zod.propValues), so discriminator lookup fails during encode(). The suggested workarounds are valid.
khanbilal732
approved these changes
Jan 29, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a warning to the Codecs documentation about using
z.codec()as adiscriminator in
z.discriminatedUnion().When a discriminator is implemented as a codec, the fast discriminator path
relies on the input (
in) schema only, which can cause.encode()to fail with"No matching discriminator".
The added note highlights this limitation and documents available workarounds
(
{ unionFallback: true }or avoiding codecs in discriminator fields).Related issue: #5593