This TypeScript error occurs when a function returns a value that does not match its declared return type. It's a type safety error that ensures functions return the expected types, preventing runtime type mismatches. Understanding return type annotations and type compatibility helps resolve this common issue.
This error indicates that a function is returning a value whose type does not match the function's declared return type. TypeScript's type checker has determined that the type of the returned expression is incompatible with the expected return type. This is a fundamental type safety check that prevents functions from returning unexpected values. The error can occur in various scenarios: returning a string when a number is expected, returning null/undefined when not allowed, returning an object missing required properties, or returning a value of a completely different type. The strict type checking catches these errors at compile time rather than allowing them to cause runtime failures.
The error message shows both the actual returned type (X) and the expected return type (Y). Pay close attention to these types and understand what the difference is. For example, if it says "Type 'string' is not assignable to type 'number'", you're returning a string where a number is expected.
// Error: Type 'string' is not assignable to type 'number'
function getNumber(): number {
return "5"; // WRONG - returning string, not number
}Look at the function signature and verify what return type it declares. Then look at your return statements and identify what type you're actually returning. In many cases, you simply need to convert the return value to the correct type or return a different value.
// CORRECT - return a number
function getNumber(): number {
return 5; // number = OK
}
// OR convert string to number
function parseNumber(): number {
const value = "5";
return parseInt(value, 10); // convert string to number
}If returning an object, verify that it has all required properties with the correct types. The error often occurs when an object is missing a required property or has a property with a different type than expected.
interface User {
id: number;
name: string;
email: string;
}
function createUser(): User {
// ERROR - missing required properties
return { name: "John" };
// CORRECT - includes all required properties
// return { id: 1, name: "John", email: "[email protected]" };
}If the error mentions "null" or "undefined", the return type may not accept these values. Either update the return type to include null/undefined, or ensure you never return null/undefined.
function getName(): string {
const name: string | null = getUserName(); // might be null
// ERROR - might return null
// return name;
// CORRECT - provide default value
return name ?? "Guest";
}
// OR update return type to include null
function getNameOrNull(): string | null {
const name: string | null = getUserName();
return name; // OK - return type includes null
}If you are absolutely certain the returned value is the correct type but TypeScript cannot infer it, you can use a type assertion with as. However, use this sparingly as it bypasses type safety.
function getValue(): number {
const value: unknown = 42;
// TypeScript doesn't know this is a number
// return value; // ERROR
// If you're certain it's a number, use 'as'
return value as number; // OK
}For generic functions, make sure type parameters are correctly inferred or explicitly specified. Sometimes TypeScript cannot infer the correct return type, so you need to specify it explicitly.
function identity<T>(value: T): T {
return value;
}
// TypeScript might infer the wrong type
const result1 = identity({ name: "John" }); // inferred as { name: string }
// Explicitly specify the type to be sure
interface User {
name: string;
age: number;
}
const result2 = identity<User>({ name: "John", age: 30 }); // must match User fullyIf the error involves null or undefined, check your TypeScript configuration. The strictNullChecks compiler option (enabled by "strict": true) makes null and undefined stricter. Understanding this setting helps you know when to update return types.
{
"compilerOptions": {
"strict": true, // Enables strictNullChecks
"strictNullChecks": true // null/undefined not allowed unless explicitly in type
}
}With strict mode, you must explicitly handle null/undefined in return types:
function getOptionalName(): string {
const user = { name: undefined };
return user.name; // ERROR: name might be undefined
// return user.name ?? ""; // CORRECT
}For async functions, remember that they always return a Promise. The return type should be Promise<T>, not just T. This is a common mistake with async functions.
// WRONG - missing Promise wrapper
async function fetchData(): string {
const response = await fetch("/api/data");
return response.json(); // ERROR: returns Promise<string>, not string
}
// CORRECT - return type is Promise<string>
async function fetchData(): Promise<string> {
const response = await fetch("/api/data");
return response.json(); // OK: returns Promise<string>
}TypeScript's return type checking follows structural typing rules. For object return types, TypeScript checks that the returned object has all required properties with compatible types (structural compatibility). For primitive types, the check is nominal (exact type match required). When using union return types (type X | type Y), ensure all code paths return a value assignable to the union. Type inference for return types can sometimes be too narrow; explicitly annotating return types can help. For generic functions, type parameters in return positions are covariant, meaning a function returning a more specific type can be used where a more general return type is expected. The strictFunctionTypes option does not affect return types (only parameter types). When working with conditional types in return positions, TypeScript may have difficulty inferring the exact type; using type assertions or simplifying the conditional type can help. For functions with multiple return statements, all return statements must return values compatible with the declared return type.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript