reportOverlappingOverload.md

April 8, 2026 · View on GitHub

Overview

reportOverlappingOverload is a diagnostic in Pylance and Pyright that warns when function overloads overlap, meaning multiple overload signatures could match the same call. This can lead to ambiguity and unexpected behavior in type checking and code execution.

Representative Issues

  • #10014: Avoid using default keyword arguments in overloads to prevent false positives for overlapping overloads.
  • #7084: Avoid using multiple TypeVars in function signatures without a clear reason to distinguish different overloads.
  • #9603: Ensure that join returns the appropriate type based on the elements in the list, avoiding mismatches between literal and non-literal strings.

Examples

Error:

from typing import overload

@overload
def process(x: int) -> str: ...
@overload
def process(x: int) -> int: ...  # Overlaps with first overload

def process(x: int) -> str | int:
    return str(x)

Fix — make overloads non-overlapping:

from typing import overload

@overload
def process(x: int) -> str: ...
@overload
def process(x: str) -> int: ...  # Different param types

def process(x: int | str) -> str | int:
    if isinstance(x, int):
        return str(x)
    return int(x)

Common Fixes & Workarounds

  1. Make overload signatures mutually exclusive so that only one matches any given call.
  2. Avoid using default keyword arguments in overloads.
  3. Use clear and distinct TypeVars only when necessary.
  4. Review the Pyright configuration documentation for options to adjust or suppress this diagnostic if needed.

See Also