TypeScript TS2322: Type 'X' is not assignable to type 'Y'

What causes this error

TS2322 fires when an expression's inferred type isn't assignable to the type expected by the destination - a function parameter, return type, variable annotation, or property assignment. TypeScript checks structural compatibility; the error message names the source and target types and (for object types) the specific property that differs.

How to fix it

1. 01

   step 1

   Read the full error message

   TS2322 names both types and (for objects) which property is incompatible. The 'Types of property X are incompatible' suffix is the most actionable line.

   Type 'User' is not assignable to type 'AdminUser'.
     Property 'role' is missing in type 'User' but required in type 'AdminUser'.

   Copy
2. 02

   step 2

   Check for null/undefined in the source type

   Most TS2322 errors come from strictNullChecks: the source type includes null or undefined but the target doesn't. Add a guard, use the non-null assertion (sparingly), or change the target type to allow null.

   // Bad - target requires non-null
   const name: string = user?.name  // TS2322 if user can be undefined
   
   // Fix 1: narrow
   if (user) {
     const name: string = user.name
   }
   
   // Fix 2: default
   const name: string = user?.name ?? ''
   
   // Fix 3: type allows undefined
   const name: string | undefined = user?.name

   Copy
3. 03

   step 3

   Check for missing properties on object types

   If you're passing an object literal to a typed slot, TypeScript checks every required property. The error names which one is missing.

   type Props = { id: number; name: string; email: string }
   
   // TS2322: Property 'email' is missing
   const p: Props = { id: 1, name: 'a' }
   
   // Fix
   const p: Props = { id: 1, name: 'a', email: '' }

   Copy
4. 04

   step 4

   Check for excess properties

   Object literals get strict excess-property checking. If you pass a property the target type doesn't define, TypeScript rejects it. Either remove it, widen the target type, or assign through an intermediate variable to bypass excess-property checking.

   type Props = { id: number; name: string }
   
   // TS2322: 'extra' does not exist in type 'Props'
   const p: Props = { id: 1, name: 'a', extra: true }
   
   // Fix - widen type or remove
   type Props = { id: number; name: string; extra?: boolean }

   Copy
5. 05

   step 5

   Check for union vs intersection mismatches

   Assigning a union to a stricter slot fails. If a variable is 'string | number' and the target wants only 'string', narrow first with typeof or a type guard.

   function getId(): string | number { return 'abc' }
   
   // TS2322
   const s: string = getId()
   
   // Fix - narrow
   const v = getId()
   const s: string = typeof v === 'string' ? v : String(v)

   Copy
6. 06

   step 6

   Use a type guard for unknown sources

   Data from JSON.parse, fetch, or external APIs is often 'unknown' or 'any'. Validate with zod, custom type predicates, or in/instanceof checks before assigning.

   function isUser(x: unknown): x is User {
     return typeof x === 'object' && x !== null && 'id' in x && 'name' in x
   }
   
   const data: unknown = JSON.parse(raw)
   if (isUser(data)) {
     const u: User = data  // OK
   }

   Copy