How to fix Overload signatures must be adjacent in TypeScript

TypeScriptINTERMEDIATELOWUpdated Dec 11, 2025· 97 views

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.

Quick fix

Fixes Overload signatures must be adjacent

// 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;
}
  1. Identify the problematic overload signatures
  2. Group all overload signatures together
  3. Check for comments between signatures
  4. Verify the implementation signature is compatible
typescript — error
// 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;
}
Overload signatures must be adjacent

What this error means

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.

Typical symptoms

  • TypeScript compiler shows error TS2394: "Overload signatures must be adjacent"
  • Build process fails with TypeScript compilation errors
  • IDE shows red squiggly lines under function declarations with overloads
  • Code that previously compiled now fails after adding new function signatures

Common causes

  1. Adding non-overload code between function overload signatures
  2. Refactoring code that moves overload signatures apart
  3. Merging code from different branches where overloads became separated
  4. Adding comments or documentation between overload signatures (though some comments are allowed)
  5. Placing variable declarations or other functions between overload signatures

How to fix "Overload signatures must be adjacent"

1Identify the problematic overload signatures

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:

typescript
// 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;
}
2Group all overload signatures together

Move all overload signatures so they appear consecutively, without any other code between them.

Corrected code:

typescript
// 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.

3Check for comments between signatures

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:

typescript
/**
 * 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.

4Verify the implementation signature is compatible

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:

typescript
// 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.

5Consider alternative approaches for complex cases

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:

typescript
function process(value: string | number): string | number {
  if (typeof value === 'string') {
    return value.toUpperCase();
  }
  return value * 2;
}

2. Use function overloads with type guards:

typescript
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).

6Run TypeScript compiler to verify fix

After reorganizing your overload signatures, run the TypeScript compiler to ensure the error is resolved:

bash
npx tsc --noEmit
# or
npm run build
# or use your project's build command

If 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

Advanced notes

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:

typescript
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.

Frequently asked questions

What does "Overload signatures must be adjacent" mean?
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.
How do I fix "Overload signatures must be adjacent"?
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.
What causes "Overload signatures must be adjacent"?
Adding non-overload code between function overload signatures Refactoring code that moves overload signatures apart Merging code from different branches where overloads became separated
Is the "Overload signatures must be adjacent" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading