pandas-dev/pandas · error · UnsupportedFunctionCall

numpy operations are not valid with groupby. Use .groupby(..

Error message

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

What it means

Raised by validate_groupby_func (compat/numpy/function.py:323-343) as UnsupportedFunctionCall when a groupby aggregation method (sum, prod, mean, median, min, max, etc.) receives positional args or unrecognized keyword args that mimic numpy's ndarray method signatures (dtype, out, keepdims, axis-as-positional, etc.). pandas groupby aggs expose their own signatures and reject numpy-style passthrough kwargs to prevent silent wrong results.

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 71959b8cb9)

Solutions

Use only the documented groupby kwargs: min_count (sum/prod), numeric_only (many), skipna where supported.
Remove numpy-specific kwargs: dtype, out, keepdims, keepdims=, and axis-as-positional-arg.
For dtype control, cast beforehand: df['c'] = df['c'].astype('float64') then groupby.sum().
For axis, groupby already operates along the grouped axis — do not pass axis.

Example fix

# before
df.groupby('key')['v'].sum(dtype='float64', min_count=1)

# after
df['v'] = df['v'].astype('float64')
df.groupby('key')['v'].sum(min_count=1)

Defensive patterns

Strategy: validation

Validate before calling

ALLOWED_SUM = {'min_count', 'numeric_only', 'skipna'}
kwargs = {'min_count': 1}
bad = set(kwargs) - ALLOWED_SUM
if bad:
    raise TypeError(f'unsupported groupby kwargs: {bad}')
df.groupby('key')['v'].sum(**kwargs)

Try / catch

try:
    df.groupby('key')['v'].sum(**kwargs)
except Exception as e:
    if 'numpy operations are not valid with groupby' in str(e):
        # strip numpy-only kwargs (dtype, out, keepdims, axis) and retry
        clean = {k: v for k, v in kwargs.items() if k not in {'dtype','out','keepdims','axis'}}
        df.groupby('key')['v'].sum(**clean)
    else:
        raise

Prevention

Consult the groupby method's signature for supported kwargs before passing any.
Never forward numpy ndarray kwargs (dtype/out/keepdims) to groupby aggs.
Cast dtypes and handle axes before the groupby, not inside the aggregation.

When it happens

Trigger: df.groupby('key').sum(skipna=False, min_count=1) with an arg not in the allowed list; df.groupby('key').prod(dtype='float64'); df.groupby('key').mean(0) (passing axis positionally). Each method has an allowed-kwarg list (SUM_DEFAULTS, STAT_FUNC_DEFAULTS, etc.); anything outside it triggers validate_groupby_func.

Common situations: Copy-pasting a numpy call pattern (np.sum(a, axis=0, dtype=...)) onto a groupby object; assuming groupby.sum accepts the same kwargs as ndarray.sum; passing axis positionally to mean/median; passing keepdims which is numpy-only.

Related errors

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