pandas-dev/pandas · error · UnsupportedFunctionCall

numpy operations are not valid with groupby. Use…

Error message

numpy operations are not valid with groupby. Use .groupby(...).{name}() instead

What it means

Raised by `validate_args_and_kwargs` (in pandas.compat.numpy.function) as an `UnsupportedFunctionCall` when a numpy-style ufunc call is made on a groupby object with positional args or unexpected kwargs. pandas blocks these because groupby dispatching should go through the named pandas method (`.sum()`, `.mean()`, etc.) rather than `np.add`/`np.multiply`-style calls.

Solutions

Use the equivalent named groupby method: `df.groupby('x').sum()` instead of `np.sum(df.groupby('x'))`.
For custom functions, define a python callable that takes the group and call `.apply`/`.transform` with it.
Pass scalar parameters by closure or partial, not as ufunc args.

Example fix

// before
np.add(df.groupby('x'), 1)

// after
def add_one(g):
    return g + 1
df.groupby('x').apply(add_one)

Defensive patterns

Strategy: validation

Validate before calling

def is_pure_groupby_call(args, kwargs, allowed):
    return len(args) == 0 and set(kwargs).issubset(set(allowed))

Try / catch

try:
    df.groupby('x').agg(func)
except Exception as e:
    if 'numpy operations are not valid with groupby' in str(e):
        df.groupby('x').apply(func)

Prevention

Use named groupby methods (.sum, .mean) instead of np.<func>.
Wrap custom logic in a python callable for apply/transform.

When it happens

Trigger: `np.sum(df.groupby('x'))`; calling `df.groupby('x').transform(np.add, 1)`; passing extra positional args to a numpy function applied through groupby; using `df.groupby('x').apply(np.mean)` with extra args.

Common situations: Porting plain-numpy code to grouped operations; reading old tutorials that recommend `np.sum` on grouped objects; trying to pass extra ufunc parameters (like `where=`) through groupby.

Related errors

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/a0eff1096f884352. Report an issue: GitHub.

Appendix: source

Thrown at pandas/compat/numpy/function.py:340

def validate_groupby_func(
    name: str,
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    allowed: list[str] | None = None,
) -> None:
    """
    'args' and 'kwargs' should be empty, except for allowed kwargs because all
    of their necessary parameters are explicitly listed in the function
    signature
    """
    if allowed is None:
        allowed = []

    extra_kwargs = set(kwargs) - set(allowed)

    if len(args) + len(extra_kwargs) > 0:
        raise UnsupportedFunctionCall(
            "numpy operations are not valid with groupby. "
            f"Use .groupby(...).{name}() instead"
        )


def validate_minmax_axis(axis: AxisInt | None, ndim: int = 1) -> None:
    """
    Ensure that the axis argument passed to min, max, argmin, or argmax is zero
    or None, as otherwise it will be incorrectly ignored.

    Parameters
    ----------
    axis : int or None
    ndim : int, default 1

    Raises
    ------
    ValueError

View on GitHub (pinned to 3b7651241d)