TypeScript TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'

Encountering TS2345 means you're passing a value of an incorrect type to a function parameter; this guide explains how to fix it.

As an API & Integration Engineer, I've spent countless hours wrangling data types and ensuring smooth information flow. The TS2345: Argument of type 'X' is not assignable to parameter of type 'Y' error is a constant companion in TypeScript development, and while it might seem frustrating at first, it's actually one of TypeScript's most valuable features. It's the compiler telling you, "Hey, the data you're giving me here isn't quite what I expected."

This guide dives deep into this common error, drawing from my personal experience to provide a practical, engineer-to-engineer approach to understanding and resolving it.

What This Error Means

At its core, TS2345 signifies a type mismatch. You're attempting to use a value of type X in a context where type Y is expected. TypeScript, being a statically typed language, performs rigorous type checking during compilation. When it encounters this error, it means the compiler has identified a potential inconsistency that could lead to unexpected behavior or bugs at runtime.

Think of it like trying to plug a USB-C cable into a USB-A port. The system (TypeScript) knows these two things aren't compatible, and it's preventing you from forcing them together, which would either not work or damage something. The error message is remarkably descriptive: it explicitly tells you what type you have (X) and what type is required (Y). This clarity is key to debugging.

Why It Happens

TypeScript's primary goal is to provide type safety and help catch errors early in the development cycle, ideally before your code even runs. The TS2345 error is a direct manifestation of this goal. It happens because you, the developer, have written code where the types don't align according to your (or your library's) type definitions.

This isn't TypeScript trying to be difficult; it's protecting you from potential runtime errors that would be much harder to debug later. Without TypeScript, passing an undefined value where an object is expected might only throw a TypeError: Cannot read properties of undefined in production, long after the code has shipped. With TypeScript, this error is caught at compile time, giving you the opportunity to fix it proactively.

In my experience, this error often appears when integrating with new APIs or external libraries where the data structures aren't immediately obvious, or when refactoring existing code and inadvertently changing a type expectation.

Common Causes

While the error message is clear, the underlying causes can be varied. Here are some of the most common scenarios that trigger TS2345:

1. Direct Type Mismatch: The most straightforward cause. You expect a number but provide a string, or an object instead of an array.
   typescript function greet(name: string) { /* ... */ } greet(123); // TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

2. Missing or Extra Properties: When working with interfaces or type aliases, the argument you pass might be missing a required property or contain properties not defined in the parameter's type.
   ```typescript
   interface User { id: number; name: string; }
   function displayUser(user: User) { / ... / }

   displayUser({ id: 1 }); // TS2345: Property 'name' is missing in type '{ id: number; }' but required in type 'User'.
   ```

3. Union Types Not Handled: If a parameter expects a union type (e.g., string | number), but your logic only accounts for one part of the union, the other part might trigger the error. This often comes up when parsing data where a field could be string or null.
   ```typescript
   type Status = 'active' | 'inactive';
   function setStatus(status: Status) { / ... / }

   setStatus('pending'); // TS2345: Argument of type '"pending"' is not assignable to parameter of type 'Status'.
   ```

4. Null or Undefined Values: A common pitfall. If a parameter expects a specific type (e.g., string), but you pass null or undefined (and strictNullChecks is enabled), you'll get this error.
   typescript function processData(data: string) { /* ... */ } let myData: string | undefined; processData(myData); // TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.

5. Asynchronous Operations: When fetching data asynchronously, the initial value of a variable might be undefined or an empty object/array, while the consuming function expects the fully loaded data structure.
   ```typescript
   interface Product { id: string; name: string; }
   let products: Product[] = []; // Initial empty array
   async function fetchProducts() {
   // products = await api.getProducts(); // This might take time
   }
   function renderProducts(items: Product[]) { / ... / }

   renderProducts(products); // If products isn't updated before render, it might cause issues depending on usage.
   // More common when a single product is expected, but you pass an array element that could be undefined.
   `` This is less about the direct assignment error and more about the *timing* of type availability, which often leads toundefined` being assigned where a concrete type is expected.

6. Incorrect Type Assertion: Sometimes, you might try to force a type using as Type, but if the underlying type is truly incompatible, the error will persist or manifest elsewhere.

Step-by-Step Fix

Resolving TS2345 usually follows a methodical debugging process. I always approach these errors with the following steps:

1. Read the Error Message Carefully: This is crucial. The message Argument of type 'X' is not assignable to parameter of type 'Y' tells you exactly what TypeScript thinks you have (X) and what it expects (Y). Pay close attention to the specific types listed. Are they string, number, boolean, an interface name, undefined, or a complex union type?

2. Inspect the Function/Method Signature: Go to the definition of the function or method that is throwing the error. Look at the type definition of the parameter (Y). What type does it explicitly expect? Check if it's an interface, a type alias, a primitive, or a union type.

   typescript // Example: Function definition function updateUser(id: string, updates: { name?: string; email?: string; }) { // ... implementation }

3. Inspect the Argument Being Passed: Now, look at the actual variable or literal value you are passing as an argument (X). What is its actual type? Hover over it in your IDE (VS Code, WebStorm, etc.) to see what TypeScript infers its type to be. This is where you identify X.

   typescript // Example: Argument being passed const userPayload = { userName: "Amara", mail: "amara@example.com" }; // TypeScript infers type of userPayload as { userName: string; mail: string; } updateUser("123", userPayload); // This would trigger TS2345

4. Identify the Type Mismatch: Compare X and Y. Where is the discrepancy?

   • Is X missing a required property that Y defines?
   • Does X have extra properties that Y doesn't allow (if Y is a literal type or a type that doesn't allow excess properties)?
   • Is X a primitive (string, number) when Y expects a different primitive?
   • Is X undefined or null when Y expects a concrete type?

   In our updateUser example above, X is { userName: string; mail: string; } and Y is { name?: string; email?: string; }. The mismatch is userName vs name and mail vs email.

5. Apply a Fix: Once the mismatch is identified, choose the appropriate solution:

   • Adjust the Argument's Type: This is the most common fix. Modify the data you're passing (X) to match the expected type (Y).
     typescript const userPayload = { name: "Amara", email: "amara@example.com" }; // Corrected updateUser("123", userPayload); // No error
   • Adjust the Parameter's Type: If you're confident that the argument's type is correct and the function's parameter type is too restrictive or simply wrong, update the function signature (Y). This is common when refactoring or evolving an API.
   • Handle Null/Undefined: If X is undefined or null but Y expects a concrete type, you might need to:
     • Provide a default value: processData(myData || 'default');
     • Add a check: if (myData) { processData(myData); }
     • Make the parameter optional in the function signature: function processData(data?: string) (making Y string | undefined).
   • Use Type Assertions (Carefully): If you, the developer, know more than TypeScript about a particular type (e.g., after a runtime check, or from an external source), you can use as to assert the type. Use this sparingly, as it bypasses type safety.
     typescript let unknownValue: any = "hello"; processData(unknownValue as string); // You're telling TypeScript it IS a string.
   • Type Narrowing: For union types, use typeof, instanceof, or property checks to narrow the type before passing it.
     typescript function handleInput(input: string | number) { if (typeof input === 'string') { console.log(input.toUpperCase()); // input is narrowed to string } else { console.log(input.toFixed(2)); // input is narrowed to number } }

This systematic approach minimizes guesswork and helps pinpoint the exact problem efficiently.

Code Examples

Here are a few concise, copy-paste ready examples illustrating common TS2345 scenarios and their fixes.

1. Primitive Type Mismatch

// Problem: Passing a number where a string is expected
function sendMessage(message: string): void {
  console.log(`Sending: ${message}`);
}

const errorCode = 500;
// sendMessage(errorCode);
// TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

// Fix: Convert the number to a string
sendMessage(String(errorCode)); // Or errorCode.toString()

2. Interface Property Mismatch

// Problem: Object missing a required property or having an incorrectly named one
interface UserProfile {
  id: string;
  username: string;
  email?: string; // Optional property
}

function displayProfile(profile: UserProfile): void {
  console.log(`User ID: ${profile.id}, Username: ${profile.username}`);
}

const partialProfile = { id: "u001", user_name: "johndoe" };
// displayProfile(partialProfile);
// TS2345: Property 'username' is missing in type '{ id: string; user_name: string; }' but required in type 'UserProfile'.
//         Property 'user_name' does not exist on type 'UserProfile'.

// Fix: Match the interface properties exactly
const correctProfile = { id: "u001", username: "johndoe" };
displayProfile(correctProfile);

3. Union Type and Null/Undefined Handling

// Problem: Passing a potentially undefined value to a non-optional parameter
interface Config {
  apiUrl: string;
  timeout?: number; // optional
}

function initializeApp(config: Config): void {
  const finalTimeout = config.timeout ?? 5000;
  console.log(`API URL: ${config.apiUrl}, Timeout: ${finalTimeout}`);
}

let serverUrl: string | undefined; // Could be undefined until loaded
// initializeApp({ apiUrl: serverUrl });
// TS2345: Argument of type '{ apiUrl: string | undefined; }' is not assignable to parameter of type 'Config'.
//         Types of property 'apiUrl' are incompatible.
//           Type 'string | undefined' is not assignable to type 'string'.

// Fix 1: Ensure serverUrl is defined before passing, e.g., using a guard
serverUrl = "https://api.example.com";
if (serverUrl) {
  initializeApp({ apiUrl: serverUrl });
}

// Fix 2: Provide a fallback (if apiUrl itself allows undefined in a default config scenario)
// Not applicable here for a required 'apiUrl', but shown for illustration for optional fields
// initializeApp({ apiUrl: serverUrl ?? 'https://default.example.com' });
// This only works if apiUrl could genuinely be a string literal or undefined.
// In this case, 'apiUrl' in Config is *required* to be a string.

Environment-Specific Notes

The TS2345 error consistently appears wherever TypeScript code is compiled, but its impact and visibility can vary across different development environments.

• Local Development: This is where you'll most frequently encounter TS2345. Modern IDEs like VS Code provide real-time feedback, highlighting the error as you type, often before you even save the file. Running tsc in your terminal or npm run dev (which typically invokes tsc --watch) will output these errors directly to the console. This immediate feedback loop is fantastic for catching issues early. In my workflow, I rely heavily on the inline errors from my IDE; it's the fastest way to debug these.

• Docker Containers: When building a Docker image for a TypeScript application, the npm run build command (or similar) will run inside the container. If your build process involves tsc, any TS2345 errors will cause the build to fail. This is critical because a failed build means a broken image, preventing deployment. I've seen this in production when a new feature introduced a type incompatibility that passed local checks (perhaps due to a missed save or a tsconfig.json difference) but failed catastrophically in the Docker build process. Ensuring your tsconfig.json is consistent across environments and running a tsc --noEmit check locally can prevent these surprises.

  ```bash

  Example Dockerfile snippet

  FROM node:alpine AS build
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  RUN npm run build # This command will fail if TS2345 errors exist

  FROM node:alpine AS production

  ... rest of your production image config

  ```

• Cloud / CI/CD Pipelines: This is where TS2345 can have the most significant impact. If your CI/CD pipeline includes a build step that runs tsc (which it absolutely should!), a TS2345 error will halt the pipeline. This prevents non-type-safe code from ever reaching staging or production environments. While frustrating, it's a critical safety net. I've configured pipelines where even a warning from TypeScript would fail the build (--maxWarnings 0), forcing strict adherence to type safety. This ensures that every deployment is rigorously checked for type consistency. When a pipeline fails due to this error, the logs will typically show the exact TS2345 messages, allowing you to pinpoint the problematic code in your source control system.

Frequently Asked Questions

Q: Can I just disable this error?
A: While you technically can disable specific TypeScript errors using // @ts-ignore or // @ts-expect-error above the problematic line, or by relaxing tsconfig.json settings, I strongly advise against it for TS2345 unless absolutely necessary (e.g., interacting with poorly typed legacy JavaScript). Disabling this error defeats the primary purpose of TypeScript: type safety. It masks potential bugs that would otherwise manifest as runtime errors. My general rule is: fix the type, don't ignore the error.

Q: What if the types look compatible but I still get TS2345?
A: This often points to subtle differences in object shapes or unexpected null/undefined possibilities.
1. Strictness: Check your tsconfig.json, especially strictNullChecks and strictPropertyInitialization. These flags introduce more rigorous checks.
2. Deep Inspection: Hover over both X and Y in your IDE. Sometimes, an interface might inherit from another, or a type alias might hide a complex union type.
3. Excess Property Checks: If you're passing an object literal, TypeScript might perform excess property checks. If Y defines properties A and B, and X has A, B, and C, it might complain that C doesn't exist on Y.

Q: Does this error affect runtime performance?
A: No, TS2345 (and all TypeScript type checking errors) occur exclusively during the compile time. Once TypeScript code is compiled into JavaScript, all type information is stripped away. The error prevents your code from being compiled into JavaScript if types don't match, meaning it never even gets to a point where runtime performance could be affected.

Q: How can I debug complex type issues that lead to TS2345?
A:
1. typeof and keyof: Use these operators within conditional types or utility types to inspect the structure of complex types.
2. Readonly<T>, Partial<T>, Pick<T, K>, Omit<T, K>: TypeScript's utility types are invaluable for understanding and manipulating existing types to fit new requirements.
3. Temporary Type Logging: Sometimes, I'll create a temporary type definition that tries to capture the type of the problematic variable, then check if it matches the expected type.
typescript type DebugX = typeof myArgument; // See what TS infers myArgument to be type DebugY = Parameters<typeof myFunction>[0]; // See what TS expects for the first parameter // Compare DebugX and DebugY
4. Isolate the Problem: Comment out sections of code until the error disappears, then gradually reintroduce them to pinpoint the exact line or expression causing the mismatch.

Related Errors

(none)