reportGeneralTypeIssues.md

April 8, 2026 · View on GitHub

Overview

reportGeneralTypeIssues is a diagnostic that flags a wide range of type-related issues in Python code, such as protocol mismatches, incorrect type narrowing, and improper use of generics. Some patterns that were originally reported under this umbrella (such as assignment and return type mismatches) have since been split into more specific rules like reportAssignmentType, reportReturnType, and reportArgumentType.

Examples

Error:

from typing import final

@final
class Base:
    pass

class Child(Base):  # Error: Base class "Base" is marked final and cannot be subclassed
    pass

Fix — correct the annotation or the value:

class Base:
    pass

class Child(Base):  # OK — Base is not marked final
    pass

Another common case — incompatible return type:

def greet(name: str) -> str:
    if not name:
        return None  # 'None' is not assignable to 'str'
    return f"Hello, {name}"

Fix:

def greet(name: str) -> str | None:
    if not name:
        return None
    return f"Hello, {name}"

Representative Issues

  • #1023: Avoid using literal types within tuples for collection elements to prevent incorrect type inference and concatenation issues.
  • #1034: Ensure type hints match actual constructor arguments.
  • #1068: Use 'TypeGuard' to indicate type checks within functions.
  • #106: Ensure all necessary imports are included and referenced.
  • #1094: Use covariant TypeVar for assignment between related types.
  • #1095: Avoid unnecessary type arguments in annotations.
  • #1274: Correctly type function parameters.
  • #1290: Use independent TypeVar declarations for nested generic classes.
  • #1295: Ensure correct order of parent class inheritance in protocols.

Common Fixes & Workarounds

  1. Review and correct type hints and annotations throughout your code.
  2. Use explicit type aliases and TypeVar declarations where needed.
  3. Match type annotations to actual usage and constructor arguments.
  4. Refactor code to avoid ambiguous or incorrect type usage.
  5. See the Pyright configuration documentation for details on configuring this rule.

See Also