Show incompatible union members in discriminated union discriminator errors

[janpaepke]

🔍 Search Terms

discriminated union error message, union type assignability error, misleading error message, discriminator property, wider union error, union literal type error, type narrowing error message

✅ Viability Checklist

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• [x] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Improve error messages when assigning objects with wider discriminator unions to discriminated union types. Currently, TypeScript reports the compatible literal as incompatible, rather than identifying the actual problematic values in the wider union that prevent assignment.

📃 Motivating Example

Consider this code [Playground Link]:

 type Discriminated =
    | { discriminator: "foo" }
    | { discriminator: "bar" };

  type UnionType = "foo" | "bar" | "baz";

  const obj = { discriminator: "foo" as UnionType };

  // Error: Type '{ discriminator: UnionType; }' is not assignable to type 'Discriminated'.
  //   Type '{ discriminator: UnionType; }' is not assignable to type '{ discriminator: "bar"; barValue: number; }'.
  //     Types of property 'discriminator' are incompatible.
  //       Type 'UnionType' is not assignable to type '"bar"'.
  //         Type '"foo"' is not assignable to type '"bar"'.
  const err: Discriminated = obj;

Current error message: Type '"foo"' is not assignable to type '"bar"'

Problem: This error is misleading. "foo" is compatible with the discriminated union. The real issue is that "baz" (present in UnionType) is not compatible with any variant of Discriminated.

Better error message (proposed): Type 'UnionType' is not assignable to the discriminator type '"foo" | "bar"'. Type(s) '"baz"' from the source union are not assignable to the target.

This directly identifies "baz" as the problematic value, making it immediately clear what needs to be fixed.

💻 Use Cases

1. What do you want to use this for?

When working with discriminated unions in large codebases, developers frequently encounter situations where:

• API responses have wider string union types than the application's internal types
• Type narrowing is attempted from generic to specific discriminated unions
• Configuration objects use string unions that need to match discriminated union variants

Better error messages would significantly reduce debugging time by directly identifying incompatible discriminator values instead of misleading developers toward compatible ones.

2. What shortcomings exist with current approaches?

The current error message:

• Points to a compatible literal type as the source of error
• Requires developers to manually compare all members of both unions to identify the actual problem
• Creates confusion, especially for TypeScript learners
• Makes the error difficult to search for and understand in complex type hierarchies

3. What workarounds are you using in the meantime?

Current workarounds include:

• Manually extracting and comparing union members using type utilities
• Adding explicit type assertions with as to silence the error (unsafe)
• Creating intermediate types with explicit exclusions: Exclude<UnionType, "baz">
• Trial-and-error removal of union members until the error clears

All of these approaches are suboptimal compared to a clear, actionable error message.

---

Note: This suggestion stems from issue https://github.com/microsoft/TypeScript/issues/62603

[alpha2420]

Hi @jankeape, I’d like to start working on this issue. Please let me know if there are any guidelines or initial steps I should follow.

[janpaepke]

Hi @alpha2420 cool - sounds great! Unfortunately I am not familiar with the correct procedures, but following the contributing guidelines, is probably a good start.

Regarding the details of this issue, I am happy to provide more context or test. As you can see there is already a discussion in #62603 outlining the basis and a Playground Link to experiment.

If any more context is needed, I'm happy to help!