Since #14819 typed copy.replace through _SupportsReplace[_P, _RT_co], a union argument is rejected whenever each member has a field the others lack, such as Circle | Square sharing name.

• ty 0.0.90, which bundles Make copy.replace more strongly typed #14819, rejects copy.replace(shape, name="renamed") today. mypy 2.4.0, which also bundles it, rejects the call and returns object.
• pyright 1.1.414 (released 2026-09-09) rejects it against main's signature; its bundled typeshed predates Make copy.replace more strongly typed #14819.
• Unions that still pass: identical fields (Left | Right), or one member's fields containing the other's.
• The call is fine at runtime.

Proposed fix: a second overload that no argument can match. Checkers then apply the spec's argument type expansion and check each union member on its own, and changes stay typed. Measured on all three: rename passes and wrong is still refused. mypy still returns object for bump, its join, linked below.

import copy
from dataclasses import dataclass


@dataclass(frozen=True)
class Circle:
    name: str
    radius: float


@dataclass(frozen=True)
class Square:
    name: str
    side: float


@dataclass(frozen=True)
class Left:
    x: int


@dataclass(frozen=True)
class Right:
    x: int


def rename(shape: Circle | Square) -> Circle | Square:
    return copy.replace(shape, name="renamed")


def bump(value: Left | Right) -> Left | Right:
    return copy.replace(value, x=1)


def wrong(shape: Circle | Square) -> Circle | Square:
    return copy.replace(shape, name=1)

ty 0.0.90 (bundled copy.replace):

repro.py:28:25: error[invalid-argument-type] Argument to function `replace` is incorrect: Expected `_SupportsReplace[((*, name: str = ..., radius: float = ...)) | ((*, name: str = ..., side: float = ...)), Circle | Square]`, found `Circle | Square`

pyright 1.1.414, against main's signature (its bundled typeshed is 289e5d3, from 2026-06-24, so I put main's _SupportsReplace and replace in a local stub):

repro_tsmain.py:28:25 - error: Argument of type "Circle | Square" cannot be assigned to parameter "obj" of type "_SupportsReplace[_P@replace, _RT_co@replace]" in function "replace"

mypy 2.4.0 (bundled):

repro.py:28: error: Incompatible return value type (got "object", expected "Circle | Square")  [return-value]
repro.py:28: error: Argument 1 to "replace" has incompatible type "Circle | Square"; expected "_SupportsReplace[[DefaultNamedArg(str, 'name'), DefaultNamedArg(float, 'radius')], object]"  [arg-type]
repro.py:32: error: Incompatible return value type (got "object", expected "Left | Right")  [return-value]

At run time on CPython 3.14.8, rename(Square("s", 1.0)) returns Square(name='renamed', side=1.0) and bump(Right(0)) returns Right(x=1).

@final
@type_check_only
class _Unreplaceable: ...

@overload
def replace(obj: _SupportsReplace[_P, _RT_co], /, *_: _P.args, **changes: _P.kwargs) -> _RT_co: ...
@overload
def replace(obj: _Unreplaceable, /, **changes: object) -> Never: ...

• mypy only splits the union once the whole union fails the first overload. Left | Right matches it as a whole through the join, so bump stays object.
• On sentinel choice: with obj: Never as the second overload's parameter, mypy reports overload-cannot-match on this stub. A @final class no argument is an instance of avoids that.

From the typing spec's overload call evaluation, step 3:

If step 2 produces errors for all overloads, perform "argument type expansion". Union types can be expanded into their constituent subtypes.

If all argument lists evaluate successfully, combine their respective return types by union to determine the final return type for the call, and stop.

pyright's maintainer has explained why a ParamSpec can't bind a union of signatures, and has pointed to overloads for other ParamSpec-and-union shapes. Neither thread is about copy.replace:

• pyright#4760: “A ParamSpec cannot take on multiple signatures. There's no way to "widen" a signature to include multiple signatures.” and “Perhaps an overload would satisfy your use case?”
• pyright#11152: "The correct way to annotate this function is with an overload."

• Make copy.replace more strongly typed #14819 (ParamSpec copy.replace, merged 2026-09-02) and Refine the copy._SupportsReplace.__replace__ signature #14786 (the covariant protocol).
• copy.replace: _SupportsReplace[RT] breaks Self-returning __replace__ with bound TypeVar #15973, and the open PR Fix copy.replace widening a bound TypeVar to its bound #15997 (written against the pre-Make copy.replace more strongly typed #14819 signature): a bound TypeVar or Self argument widened to its bound. Not addressed by the overloads above.
• mypy's join:
  • copy.replace type inference regression: breaks Self-returning __replace__ with bound TypeVar mypy#21672: the same widening in mypy;
  • abs(Union[int, Decimal]) is inferred as object mypy#8601: a protocol solved from a union gives object;
  • (🎁) Perform 'union math' on non overloaded calls mypy#13493: union math on non-overloaded calls.
• replace: a union or union-bound TypeVar comes back as Struct (mypy), and a union whose members each have their own field is rejected (pyright, ty) JPHutchins/salix#359, the downstream report: the same shape in a dataclass_transform stub.