Overload signature not compatible with Implementation signature

Overload signature not compatible with Implementation signature #

The error "This overload signature is not compatible with its implementation signature" occurs when the implementation signature of the function is not compatible with all of its overload signatures. To solve the error, make the implementation compatible with all overload signatures.

Here is an example of how the error occurs.

Copied!
function example(str: string): void;
// ⛔️ Error: This overload signature is not
// compatible with its implementation signature.
function example(num: number): void;
function example(arg: string) {}

The first two lines are called the overload signatures, the third line is the function implementation.

The first overload signature takes a string as a parameter and the second a number.

To solve the error, we have to make sure the implementation signature is compatible with all of the overload signatures.

Copied!
function example(str: string): void;
function example(num: number): void;
function example(arg: string | number) {}

Now the parameter in the implementation signature has a compatible type with all of the overload signatures.

Here is a complete example of a function with 2 overload signatures.

Copied!
function createDate(timestamp: number): Date;
function createDate(year: number, month: number, day: number): Date;
function createDate(
  yearOrTimestamp: number,
  month?: number, // 👈️ mark optional
  day?: number, // 👈️ mark optional
): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(yearOrTimestamp, month, day);
  }

  return new Date(yearOrTimestamp);
}

const date1 = createDate(1647474643657);
console.log(date1); // 👉️ Thu Mar 17 2022

const date2 = createDate(2023, 4, 24);
console.log(date2); // 👉️ Wed May 24 2023

The Date() constructor can be passed different parameters to create a Date object.

In the first signature, the function takes a timestamp (number) parameter and returns a Date object.

Notice that the first overload signature only takes a single parameter, whereas the second takes 3 parameters.

In this case, we have to mark the second and third parameters as optional.

Copied!
function createDate(timestamp: number): Date;
function createDate(year: number, month: number, day: number): Date;
function createDate(
  yearOrTimestamp: number,
  month?: number,
  day?: number,
): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(yearOrTimestamp, month, day);
  }

  return new Date(yearOrTimestamp);
}

// ⛔️ Error: No overload expects 2 arguments,
// but overloads do exist that expect either 1 or 3 arguments.ts(2575)
const date3 = createDate(2023, 4);

Even though the line where we call the createDate function satisfies its implementation signature, because the function has 2 optional parameters, we get an error.

None of the overload signatures expect 2 arguments. The first overload signature expects 1 and the second expects 3.

You should also make sure that the return types of the overload signatures and the implementation signature are compatible.

Copied!
// ⛔️ Error: This overload signature is not
// compatible with its implementation signature.ts(2394)
function example(str: string): string;
function example(num: number): number;
function example(arg: string | number): number {}

Notice that the first overload signature has a return type of string, and the second has a return type of number.

The implementation signature cannot have a return type of number, because it is not compatible with the first overload signature.

Copied!
// ✅ Implementation signature compatible with Overload signatures
function example(str: string): string;
function example(num: number): number;
function example(arg: string | number): number | string {}

Just like in the example with the createDate function, if one of your overload signatures takes more parameters than the others, mark them as optional in your implementation signature.

Copied!
function example(str: string): void;
function example(num: number, num2: number): void;
function example(strOrNum: string | number, num2?: number) {}

Now consumers of our function are able to call it with a single parameter - a string, which would satisfy the first overload signature.

They are also able to call it with 2 parameters of type number, but the function cannot be invoked with a single parameter of type number, even though its second parameter is marked as optional.

Copied!
function example(str: string): void;
function example(num: number, num2: number): void;
function example(strOrNum: string | number, num2?: number) {}

// ✅ OK
example('hello');

// ✅ OK
example(1, 2);

// ⛔️ Error: The call would have succeeded against
// this implementation, but implementation
// signatures of overloads are not externally visible.
example(1);

The implementation signature of the function cannot be called directly, you have to call one of the overload signatures.

Conclusion #

The error "This overload signature is not compatible with its implementation signature" occurs when the implementation signature of the function is not compatible with all of its overload signatures. To solve the error, make the implementation compatible with all overload signatures.