Resolving the 'Argument of type 'X' is not assignable to parameter of type 'Y'' Error in TypeScript
Introduction
If you write TypeScript regularly, at some point you will see the compiler complain with the message: "Argument of type 'X' is not assignable to parameter of type 'Y'". This error is one of the most common friction points when moving from loose JavaScript assumptions to TypeScript's static checking. It can appear in small code snippets or during complex generic operations, and the root cause ranges from simple typos to deep type-system issues like variance and inference problems.
In this article you will learn the full lifecycle of diagnosing and fixing this error. We will cover the typical roots of the problem, including primitive and literal mismatches, structural typing issues, function parameter variance, generics with constraints, unions and overloads, and problems introduced by missing declaration files or incorrect compiler settings. You will get practical code examples, step-by-step remediation patterns, and a reproducible debugging workflow you can adopt immediately.
By the end of this tutorial you will be able to: read and interpret the error in context, decide whether to fix the code, change the types, or add safe casts, and choose the right long-term fix to avoid regression. We will also show how to tune your tsconfig and how to handle third-party library typings so you no longer see this error unexpectedly during builds.
Background & Context
TypeScript's type system is structural and designed to help you catch mismatches at compile time. The "Argument of type 'X' is not assignable to parameter of type 'Y'" error is thrown when the compiler determines that the provided argument cannot be used where a parameter of a given type is expected. This can happen with simple assignments, when calling functions, passing callbacks, or when working with generics.
Understanding why the error occurs requires some knowledge of TypeScript's inference rules, literal types, unions, intersections, and the special cases of function parameter variance. Because TypeScript checks shapes rather than names, sometimes two types that look similar still fail to be assignable if they differ on readonly modifiers, extra properties, or generic constraints. The more familiar you are with these concepts, the faster you'll be able to diagnose and resolve the error.
If you want a compact primer on the broader class of "X is not assignable to Y" errors, our focused guide gives examples and common fixes for similar type mismatches: Understanding and Fixing the TypeScript Error: Type 'X' is not assignable to type 'Y'.
Key Takeaways
- The error means the compiler found a legitimate type mismatch; fix by changing the value, the parameter type, or using a controlled assertion.
- Literal widening, unions, and readonly modifiers are common subtle causes.
- Function arguments can fail due to variance and differing parameter shapes.
- Generics require constraints to ensure type compatibility.
- Missing or incorrect declaration files often cause this error when using JS libraries; add or fix .d.ts.
- Use tsconfig strict flags to find issues early, and prefer small, safe casts over broad uses of any.
Prerequisites & Setup
This tutorial assumes intermediate TypeScript knowledge: you know basic types, interfaces, functions, generics, and how tsconfig.json works. To follow the examples, you will need:
- Node.js and npm/yarn
- TypeScript installed locally (recommended):
npm install --save-dev typescript - A simple project with a tsconfig.json. If you do not have one, run
npx tsc --initand refer to the basics in the TypeScript tsconfig guide: Introduction to tsconfig.json: Configuring Your Project
Make sure your editor is set up to use the workspace TypeScript version to mirror the compiler behavior.
Main Tutorial Sections
1) Anatomy of the Error: a simple example
Start with the simplest reproduction so you can see the error in context.
function greet(name: string) {
console.log('Hello', name);
}
const maybeName: string | undefined = undefined;
greet(maybeName); // Argument of type 'string | undefined' is not assignable to parameter of type 'string'Why does this happen? The function expects a plain string, but you passed a union that includes undefined. The safest fix is to ensure the argument matches the parameter's contract: either refine the type, provide a default, or change the parameter to accept the union.
Fix options:
if (maybeName) greet(maybeName);
// or
greet(maybeName ?? 'guest');
// or change function signature
function greet(name: string | undefined) { ... }This basic pattern appears everywhere; learning to narrow union types is the first tool in your toolbox.
2) Literal types and widening pitfalls
TypeScript widens literal values by default. That can produce mismatches when you expect a narrower literal type.
type Mode = 'read' | 'write';
const m = 'read'; // type is string (widened)
function setMode(mode: Mode) {}
setMode(m); // Argument of type 'string' is not assignable to parameter of type 'Mode'Fix with a const assertion so the literal is preserved:
const m = 'read' as const; // type 'read' setMode(m); // OK
Or declare the variable with the union type explicitly. Understanding widening helps you avoid accidental generalization that breaks compatibility.
3) Structural typing, extra properties, and object literals
TypeScript compares object shapes. Extra or missing properties can cause assignability errors, especially with fresh object literals.
type User = { name: string };
function processUser(u: User) {}
processUser({ name: 'Ann', role: 'admin' }); // Error: Object literal may only specify known propertiesObject literals are checked for excess properties; one fix is to assign the literal to a variable first:
const raw = { name: 'Ann', role: 'admin' };
processUser(raw); // OK assuming structural compatibilityIf you often encounter property issues in larger codebases, review related errors like "property does not exist on type": Property 'x' does not exist on type 'Y' Error: Diagnosis and Fixes'.
4) Function parameter mismatches and variance
Function types introduce variance considerations. TypeScript treats parameters contravariantly in theory, but to be pragmatic it sometimes uses bivariance for callbacks — this can result in surprising errors in strict checking.
Example:
type HandlerA = (x: { id: number }) => void;
type HandlerB = (x: { id: number; name: string }) => void;
let hA: HandlerA;
let hB: HandlerB;
hA = hB; // Error in strict mode: parameter type incompatibleIf a function expects a broader type, passing a narrower function is unsafe. The safe fix is to align signatures or use generics to abstract the difference. For callback-heavy APIs, declare parameter types carefully to avoid accidental mismatches.
5) Generics and constrained types
Generics are powerful but introduce assignability problems when constraints are missing.
function getFirst<T>(arr: T[]): T { return arr[0]; }
const numbers = [1, 2, 3];
const value: string = getFirst(numbers); // Error: number not assignable to stringEnsure generic inference matches your intended type, or provide explicit type arguments. Use constraints when you require properties:
function pluck<T extends object, K extends keyof T>(obj: T, key: K) {
return obj[key];
}
pluck({ name: 'Ann' }, 'name'); // OKFor more advanced library typing, use constrained generics rather than casting to any.
6) Union, intersection, and overload behavior
Unions mean a value can be multiple types. If a function expects A but you pass A | B, the compiler will reject it. Conversely, intersections can add properties the caller does not provide.
function onlyString(x: string) {}
const maybe = Math.random() > 0.5 ? 'hi' : 1;
onlyString(maybe); // ErrorOverloads can also confuse assignability if the implementation signature is wider than callers expect. Align your overloads and implementation signature carefully.
7) Declarations and third-party libraries
A frequent cause in real projects is using JavaScript libraries without proper type declarations. When types are missing, or mismatched, the compiler will produce assignability errors where the library's runtime shape doesn't match the typed shape.
If you hit issues, check for missing or wrong declarations and follow a systematic approach: search DefinitelyTyped, add or amend .d.ts, or write a simple module declaration. See guides on resolving these issues: Troubleshooting Missing or Incorrect Declaration Files in TypeScript and Using DefinitelyTyped for External Library Declarations.
If you need to write a lightweight declaration to unblock work, our tutorial on authoring minimal declarations is helpful: Writing a Simple Declaration File for a JS Module.
8) Safe casting, unknown, and when to use any
Casting can silence the error, but use it judiciously.
- Use unknown instead of any when you want to force a runtime or type guard before using the value.
- Use
asassertions only when you have external knowledge that the compiler does not.
Example:
declare const payload: unknown;
if (typeof payload === 'string') {
use(payload); // narrowed safely
}
// Avoid this unless necessary:
const x = payload as string; // bypasses safetyFavor runtime checks and type guards over blanket assertions.
9) Compiler flags and module resolution
Sometimes assignability errors come from configuration, not code. Flags like strict, noImplicitAny, and exactOptionalPropertyTypes change checking behavior. If you see unexpected errors, inspect tsconfig and consider enabling stricter checks to catch problems early.
Start here: Introduction to tsconfig.json: Configuring Your Project. Also read about the benefits of opting into stronger checking with Using noImplicitAny to Avoid Untyped Variables and the broader Understanding strict Mode and Recommended Strictness Flags.
Module resolution issues can cause types to be imported differently than expected; use Controlling Module Resolution with baseUrl and paths if you frequently encounter path-based mismatches.
10) Debugging workflow and tooling
Create minimal repros, add ts-node or tsc checks, and use the editor's quick-fix hints. When debugging complex builds, generate source maps for compiled outputs to map runtime errors back to the TS code: Generating Source Maps with TypeScript (sourceMap option).
If your project mixes JS and TS, review patterns for calling between the two to ensure types align and that declaration files reflect runtime behavior: Calling JavaScript from TypeScript and Vice Versa: A Practical Guide.
A recommended reproducible process:
- Reduce to a minimal example that reproduces the error.
- Inspect the actual inferred types in your editor (hovering often shows the culprit).
- Try a narrowing or casting approach locally; if it fixes the problem, codify the fix appropriately.
- Add tests or types that prevent regression.
Advanced Techniques
Once you understand common causes, adopt advanced patterns to prevent and elegantly resolve these errors:
- Use conditional types and mapped types to transform external types into shapes your APIs expect. Conditional types can express constraints that previously required manual assertions.
- Employ the new satisfies operator (TypeScript 4.9+) to ensure object literals conform to a target type without losing narrowed literal types; this often prevents accidental widening.
- Create assertion functions that act as runtime guards and inform the type checker, using the "asserts" return type to narrow types in calling code.
- For library authors, export precise generic overloads and use utility types like Readonly, Required, and Pick to express contract expectations clearly.
- When contributing to third-party typings, prefer augmenting the types in DefinitelyTyped or offering PRs so your fix helps others: Using DefinitelyTyped for External Library Declarations.
These techniques reduce brittle casts and surface clear contracts to consumers of your code.
Best Practices & Common Pitfalls
Dos:
- Narrow union types before passing them into functions.
- Prefer runtime checks with type guards over broad assertions.
- Keep your tsconfig strict settings enabled for new projects.
- Write small, well-scoped interfaces and avoid overly permissive any types.
Don'ts:
- Avoid mass-casting to any to silence errors; it trades safety for silence.
- Don’t rely on implicit any behavior in function signatures when stricter checking is expected.
- Avoid changing public APIs just to appease internal typing differences; change at the call site if appropriate.
Troubleshooting tips:
- Hover in VS Code to inspect inferred types — often the mismatch is obvious once you see both sides.
- Reproduce the issue in a minimal sandbox. This often reveals whether the problem is local or due to library typings.
- If a library is the root cause, check for updated types on npm or DefinitelyTyped and consider writing a quick declaration file while you wait: Troubleshooting Missing or Incorrect Declaration Files in TypeScript.
Real-World Applications
This error commonly appears in web apps, backend services, and libraries:
- UI frameworks: passing props with optional fields into components that expect required props. Fix with defaulting or prop type updates.
- API clients: deserializing JSON into typed models may produce unions; use validators to guarantee correct shapes before passing to typed functions.
- Event handlers: DOM event types and custom events often have mismatched shapes; ensure your event parameter types align with actual event payloads.
When working across modules or packages, ensure your declarations and package exports accurately reflect runtime objects to avoid surprises during build or runtime.
Conclusion & Next Steps
"Argument of type 'X' is not assignable to parameter of type 'Y'" is a useful compiler signal that something in your code or configuration needs attention. Approach it methodically: reproduce, inspect inferred types, narrow or assert safely, or update declarations. Strengthen your codebase with strict compiler options and precise typings to catch problems early.
Next steps: enable stricter tsconfig flags, practice narrowing techniques, and learn to author declaration files for smooth interop with JS libraries.
Enhanced FAQ
Q: I keep getting this error when calling an external library; what should I check first? A: First, check that the library's type declarations match its runtime API. Look for a corresponding @types package or a bundled .d.ts. If missing or incorrect, consult Troubleshooting Missing or Incorrect Declaration Files in TypeScript and consider adding a temporary declaration or installing types from DefinitelyTyped: Using DefinitelyTyped for External Library Declarations.
Q: When is it OK to use a type assertion to silence the error? A: Use assertions when you have reliable runtime guarantees that the compiler cannot infer—for example, when interacting with an external system where you validate data at runtime. Prefer using assertion functions or narrowing and avoid broad assertions like casting everything to any.
Q: Why do object literals sometimes error about extra properties while variables don't? A: TypeScript applies excess property checks to fresh object literals to help catch typos. Assigning the literal to a variable first removes the freshness and allows structural compatibility, but you should still consider whether the extra property indicates a design issue.
Q: How do generics cause this error in complex code paths? A: If generic parameters are inferred differently at call sites, the return and parameter types can be incompatible. Use explicit type parameters or constraints (extends) to force the shape you need. Adding a constraint prevents accidental inference of incompatible shapes.
Q: What role does tsconfig play here? Could compiler flags cause or hide this error? A: Yes. Flags like strict, noImplicitAny, exactOptionalPropertyTypes, and strictFunctionTypes change assignability rules. Turning on stricter flags will surface more errors but leads to better long-term safety. Review your project tsconfig settings and consult Introduction to tsconfig.json: Configuring Your Project for guidance.
Q: I'm seeing errors only in CI but not locally. Why? A: Differences in TypeScript versions between your editor and CI can lead to discrepancies. Ensure your project uses a pinned TypeScript version and your editor uses the workspace version. Also verify tsconfig paths and module resolution settings, as CI might run a different node resolution context.
Q: Is there a performance cost to enabling strict mode to avoid these errors? A: Compiler checks add little build time compared to the value they provide. The runtime performance is unaffected. Use strict mode for correctness and to prevent runtime bugs that are costlier to fix.
Q: How do I fix complex callback mismatches in event-heavy code? A: Declare precise callback types, prefer generics for reusable patterns, and avoid overly general parameter types. Where necessary, refactor to small adapter functions that transform the payload into the expected shape rather than rely on casts.
Q: Where can I learn more about other related compile errors? A: For a broader overview of common TypeScript errors and steps to fix them, see Common TypeScript Compiler Errors Explained and Fixed. That guide groups recurring issues and provides patterns to reduce friction.
Q: How do I handle a mixed JS/TS codebase where types are constantly mismatched? A: Consider adding JSDoc with @ts-check to key JavaScript files to detect shapes early: this is a good transitional strategy. Also, write small declaration files for JS modules and gradually migrate modules to TypeScript. See guides like Calling JavaScript from TypeScript and Vice Versa: A Practical Guide and the declaration writing tutorial Writing a Simple Declaration File for a JS Module.
If you still have a specific example that confuses you, paste a minimal reproducible example and we can walk through the diagnostics step by step.