discriminatedUnion fails on encode() when discriminator is a ZodCodec

[MadL0rd]

Description

When using z.discriminatedUnion with a discriminator field implemented as a ZodCodec,
decode() works correctly, but encode() fails at runtime with
No matching discriminator.

This happens even though:

• the types of decode() / encode() inputs are correct
• the codec itself is fully bidirectional
• the decoded domain object is valid

The issue appears to be that discriminatedUnion attempts to select a branch
before encoding the discriminator field, using the domain value instead of
the encoded (raw) value.

---

Reproducible example

const LiteralTestCodec1 = z.codec(z.literal(1), z.literal('one'), {
    decode: (raw) => 'one' as const,
    encode: (domain) => 1 as const,
})

const LiteralTestCodec2 = z.codec(z.literal(2), z.literal('two'), {
    decode: (raw) => 'two' as const,
    encode: (domain) => 2 as const,
})

const TestUnionSchema = z.discriminatedUnion(
    'type',
    [
        z.object({
            type: LiteralTestCodec1,
            valueString: z.string(),
        }),
        z.object({
            type: LiteralTestCodec2,
            valueNumber: z.number(),
        }),
    ]
)

const domain = TestUnionSchema.decode({
    type: 1,
    valueString: 'test value',
})

const raw = TestUnionSchema.encode({
    type: 'one',
    valueString: 'test value',
})

---

Actual result

decode() works correctly.

encode() throws the following error:

ZodError: [
  {
    "code": "invalid_union",
    "errors": [],
    "note": "No matching discriminator",
    "discriminator": "type",
    "path": ["type"],
    "message": "Invalid input"
  }
]

---

Expected behavior

Given that:

• the discriminator codec is bidirectional
• encode() should produce a valid raw representation

encode() is expected to succeed and return:

{
    type: 1,
    valueString: "test value"
}

---

Notes / Workaround

At the application level, this issue can be worked around by enabling
{ unionFallback: true } when creating the discriminatedUnion.

This forces Zod to fall back to full union validation instead of the fast
discriminator-based path.

However, this behavior is surprising when combining:

• z.discriminatedUnion
• codecs used as discriminator fields
• encode() direction

---

Possible directions

Below are concrete implementation-oriented ideas based on the current internal behavior of ZodDiscriminatedUnion (not prescriptions).

1. Make discriminator resolution context-aware

Currently, branch selection in ZodDiscriminatedUnion is based on a precomputed map:

const opt = disc.value.get(input?.[def.discriminator] as any);
if (opt) {
  return opt._zod.run(payload, ctx) as any;
}

Where disc is a Map computed once from propValues, derived by recursively inspecting each option schema and then cached.

For ZodCodec, propValues are defined as:

util.defineLazy(inst._zod, "propValues", () => def.in._zod.propValues);

This means:

• discriminator values are taken exclusively from the in schema
• there is no context available to distinguish decode vs encode
• during encode(), discriminator resolution still relies on forward (in) values

One possible direction would be to make propValues resolution context-aware, for example by turning it into a function that receives encoding direction from the parsing context (e.g. ctx.direction: "forward" | "backward"), allowing codecs to expose discriminator values appropriate to the current direction.

---

2. Introduce a backward discriminator path

An alternative (more explicit) approach would be to keep the existing fast-path intact, but add a mirrored mechanism for the backward direction:

• introduce propValuesBackward (mirroring propValues)
• derive it from def.out instead of def.in for codecs
• build and cache a separate discBackward map
• select between disc and discBackward based on encoding direction

This would preserve:

• current performance characteristics
• clear separation of forward (decode) and backward (encode) discriminator resolution

while allowing discriminators implemented as codecs to work symmetrically.

---

Documentation note

Regardless of implementation, this behavior could also be documented explicitly as a current limitation of combining:

• z.discriminatedUnion
• codecs used as discriminator fields
• encode() direction

See: https://zod.dev/codecs

---

Question

Is this behavior considered an intentional limitation of discriminatedUnion,
or would a change in discriminator resolution (or explicit documentation of the limitation) be acceptable?

If this aligns with the intended direction of the API, I am willing to prepare a PR.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔ ｜ pullfrog.com}

[dosubot]

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

I'm a bot trained on Zod's codebase and issues.

You're absolutely right—this is a current limitation in Zod: when using a ZodCodec as the discriminator in a discriminatedUnion, encode() fails because the branch selection always uses the forward (decode) values from the codec's input schema, even during encoding. The implementation does not consider the encoded (raw) value, so it can't match the correct branch when encoding domain objects. This is confirmed by both the code and the documentation, which notes that discriminators are resolved from the input schema and suggests making discriminator resolution context-aware or maintaining separate maps for encode/decode directions as possible improvements. The recommended workaround is to use { unionFallback: true } to bypass the fast-path and allow encoding to succeed, though this is less efficient and not ideal for all use cases source.

This limitation isn't explicitly documented in the main docs, so a documentation update or an implementation change would be valuable. Maintainers have welcomed PRs for expanding discriminated union capabilities in the past, and your proposed directions (context-aware resolution or a mirrored backward map) align well with the needs here. If you'd like to prepare a PR or a documentation update, that would likely be considered—tagging @colinhacks for feedback on preferred direction is a good next step.

If this answers your question, feel free to close the issue! If you have more details or want to discuss implementation specifics, let me know.

To reply, just mention @dosu.

---

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

   

[MadL0rd]

cc @colinhacks

This issue has been idle for a couple of weeks, so I wanted to ask whether this
behavior is considered an intentional limitation of discriminatedUnion
or something that would be acceptable to address.

I’ve looked into the internal mechanics (disc / propValues) and outlined a
couple of concrete implementation options above. I’d be happy to prepare a PR
once there’s clarity on the intended direction.

[dosubot]

Based on the codebase and docs, the current behavior—where discriminatedUnion with a codec-based discriminator fails on encode()—is a direct result of how discriminator resolution always uses the forward (decode) values from the input schema, even during encoding. There’s no direction-aware logic or special handling for codecs as discriminators, so this isn’t explicitly documented as intentional, but appears to be a byproduct of the fast-path implementation source.

Your proposed solutions (context-aware discriminator resolution or a mirrored backward map) directly address the technical gap. I haven’t found any maintainer comments or docs stating whether this is an intentional limitation or if a PR would be accepted. Tagging @colinhacks for feedback: would you prefer this be documented as a limitation, or would a PR to address encode/decode directionality for codec-based discriminators be welcome?

If you want to discuss implementation specifics or need help drafting a PR, let me know! 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}

   

[HarrySeop]

Hello @MadL0rd,

Thanks for the detailed analysis and proposed solutions in this issue. I've also looked into it and believe I understand the root cause and a possible fix.

You mentioned you might be willing to prepare a PR — are you currently working on it, or would it be okay if I took a shot at implementing the fix?

I just want to avoid duplicating effort. Please let me know your preference.

Thanks!

[MadL0rd]

@HarrySeop I really appreciate the interest in the issue.

For now, I’ve opened a documentation PR to explicitly call out the limitation and available workarounds:
#5650

Before moving forward with a behavioral change, I’d prefer to wait for guidance from the core maintainers on whether this is considered an intentional limitation or something they’d want to support at the API level. Once there’s clarity on direction, we can see what the best next step is.

Thanks again for digging into this.