Show incompatible union members in discriminated union discriminator errors

🔍 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

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• 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

Start with the motivating discriminated-union example and compare the current diagnostic with the proposed one. Trace the type-checker path for assignability and discriminated union discriminator errors, then verify that the completed behavior identifies incompatible source-union members such as "baz" without changing runtime output.