This TypeScript error occurs when function overload signatures are separated by other code. Overload signatures must appear consecutively to define multiple function signatures for type checking. The fix involves reorganizing your function declarations so all overload signatures are grouped together.
TypeScript supports function overloading, which allows you to define multiple function signatures for a single implementation. This is useful when a function can accept different parameter types or return different types based on the input. The "Overload signatures must be adjacent" error occurs when TypeScript encounters overload signatures that are not placed consecutively in your code. TypeScript requires all overload signatures (the declarations without implementations) to appear one after another, followed by a single implementation signature. This restriction exists because TypeScript needs to clearly distinguish between the overload declarations and the actual implementation. If other code appears between overload signatures, the compiler cannot properly associate them with the implementation.
Locate the function with overload signatures in your code. Look for multiple function declarations with the same name but different parameter types or return types.
Example of incorrect code:
// First overload
function processInput(value: string): string;
// Some other code or variable declaration - THIS CAUSES THE ERROR
const config = { debug: true };
// Second overload
function processInput(value: number): number;
// Implementation
function processInput(value: string | number): string | number {
return value;
}Move all overload signatures so they appear consecutively, without any other code between them.
Corrected code:
// First overload
function processInput(value: string): string;
// Second overload - NOW ADJACENT
function processInput(value: number): number;
// Other code can go here
const config = { debug: true };
// Implementation
function processInput(value: string | number): string | number {
return value;
}All overload signatures must appear one after another, followed by any other code, then the implementation.
While most comments are allowed between overload signatures, some comment formats might cause issues. If you have JSDoc comments or other documentation between signatures, try moving them above the first overload or below the last one.
Example with comments:
/**
* Processes string input
* @param value - String to process
* @returns Processed string
*/
function processInput(value: string): string;
/**
* Processes number input
* @param value - Number to process
* @returns Processed number
*/
function processInput(value: number): number;
// Implementation
function processInput(value: string | number): string | number {
return value;
}This is generally acceptable, but if you encounter issues, move all comments to a single location.
Ensure your implementation signature is compatible with all overload signatures. The implementation should handle all the parameter types and return types defined in the overloads.
Example of compatible implementation:
// Overloads
function formatData(data: string): string;
function formatData(data: number): string;
function formatData(data: boolean): string;
// Implementation that handles all cases
function formatData(data: string | number | boolean): string {
return String(data);
}The implementation uses a union type for the parameter and returns string, matching all overload signatures.
If your function signatures are very different or you need to separate them for readability, consider these alternatives:
1. Use union types in a single signature:
function process(value: string | number): string | number {
if (typeof value === 'string') {
return value.toUpperCase();
}
return value * 2;
}2. Use function overloads with type guards:
function isString(value: any): value is string {
return typeof value === 'string';
}
function process(value: string): string;
function process(value: number): number;
function process(value: string | number): string | number {
if (isString(value)) {
return value.toUpperCase();
}
return value * 2;
}3. Use method overloading in classes (which has the same adjacency requirement).
After reorganizing your overload signatures, run the TypeScript compiler to ensure the error is resolved:
npx tsc --noEmit
# or
npm run build
# or use your project's build commandIf the error persists, check for:
- Hidden characters or whitespace issues between signatures
- Nested functions or methods with the same name
- Import/export statements between signatures
- Any code generation tools that might be inserting content between signatures
TypeScript Overload Resolution: When you call an overloaded function, TypeScript uses the overload signatures (not the implementation) to determine type compatibility. The compiler tries each overload signature in order until it finds one that matches the arguments.
Method Overloading: The same adjacency rule applies to method overloads in classes and interfaces:
class Calculator {
add(a: number, b: number): number;
add(a: string, b: string): string;
add(a: any, b: any): any {
return a + b;
}
}Constructor Overloading: Constructors can also be overloaded, following the same adjacency rule.
Limitations: Overload signatures don't appear in the compiled JavaScript - they're purely for TypeScript type checking. The JavaScript output only contains the implementation.
ESLint Rule: The TypeScript ESLint plugin includes a rule @typescript-eslint/adjacent-overload-signatures that can enforce this requirement in your codebase.
Type parameter 'X' is not used in the function signature
How to fix "Type parameter not used in function signature" in TypeScript
Type parameter 'X' is defined but never used
How to fix "Type parameter is defined but never used" in TypeScript
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