Argument of type X is not assignable to parameter of type Y — What It Means and How to Fix It

The TypeScript compiler throws "Argument of type X is not assignable to parameter of type Y" when you pass a value whose type doesn't match what the function or method expects.

What "Argument of type X is not assignable to parameter of type Y" Means

It's a compile-time type mismatch. You're calling a function with a value that doesn't satisfy the parameter's declared type. TypeScript checks this statically — before any code runs — so this error never appears in the browser or Node.js at runtime. It only shows up in your editor or when running tsc.

Why It Happens

The most common causes, in order of frequency:

1. Narrow vs. wide types: You pass a string | undefined where the function expects string. The union type is wider than what the parameter allows.
2. Structural mismatch: The object you pass is missing required properties or has properties with incompatible shapes.
3. Type inference drift: You declared a variable with let and reassigned it to different types, so TypeScript infers a union that doesn't fit.

Example Code That Triggers It

Here's a minimal, runnable example that produces this exact error in a Node.js environment with TypeScript:

// save as error.ts, run with: npx tsc error.ts
function processUser(user: { name: string; age: number }) {
  console.log(`${user.name} is ${user.age} years old`);
}

const maybeUser: { name: string; age: number } | null = null;
processUser(maybeUser); // Error: Argument of type '{ name: string; age: number; } | null' is not assignable to parameter of type '{ name: string; age: number; }'

The error message reads: Argument of type '{ name: string; age: number; } | null' is not assignable to parameter of type '{ name: string; age: number; }'. TypeScript won't let you pass null where a non-null object is required.

How to Fix It

Add a null check before the call:

function processUser(user: { name: string; age: number }) {
  console.log(`${user.name} is ${user.age} years old`);
}

const maybeUser: { name: string; age: number } | null = null;

if (maybeUser) {
  processUser(maybeUser); // Works — TypeScript narrows the type inside the if block
}

The fix works because TypeScript's control-flow analysis narrows maybeUser from { name: string; age: number } | null to just { name: string; age: number } inside the if block. The narrowed type is now assignable to the parameter.

Common Mistakes That Cause This

Mistake 1: Ignoring optional chaining outcomes. You write user?.address and pass the result directly to a function expecting Address. The result is Address | undefined, which won't match. Always handle the undefined case explicitly.

Mistake 2: Using any to silence the error, then hitting it downstream. You cast to any, the error disappears, but later you get a runtime crash when the any value doesn't have the expected shape. The error is telling you something real — don't bypass it.

When Should You Worry About This?

Worry when the error appears in code you're shipping to production, especially in Next.js API routes or Express handlers where request bodies are involved. If you're passing parsed JSON to a function with a strict interface, this error is your safety net. It's also a red flag if you see it frequently in a codebase — it usually means types are drifting from reality. But if it happens once during refactoring, it's working as designed. Fix it properly with type guards or validation, not as casts.

One specific thing to check first: look at the exact type of X in the error message — if it includes | undefined or | null, a simple truthy check before the call will resolve it 80% of the time.