pandas-dev/pandas · error · TypeError

Must provide 'func' or named aggregation **kwargs.

Error message

Must provide 'func' or named aggregation **kwargs.

What it means

Raised by validate_func_kwargs (apply.py:2317) as a TypeError when no kwargs at all are provided to a named-aggregation-style call. The function is invoked when pandas is expecting named aggregation; if the kwargs dict is empty there is nothing to aggregate, so pandas raises a guidance message directing the user to supply func or named-agg kwargs.

Source

Thrown at pandas/core/apply.py:2317

        List of user-provided keys.
    func : List[Union[str, callable[...,Any]]]
        List of user-provided aggfuncs

    Examples
    --------
    >>> validate_func_kwargs({"one": "min", "two": "max"})
    (['one', 'two'], ['min', 'max'])
    """
    tuple_given_message = "func is expected but received {} in **kwargs."
    columns = list(kwargs)
    func = []
    for col_func in kwargs.values():
        if not (isinstance(col_func, str) or callable(col_func)):
            raise TypeError(tuple_given_message.format(type(col_func).__name__))
        func.append(col_func)
    if not columns:
        no_arg_message = "Must provide 'func' or named aggregation **kwargs."
        raise TypeError(no_arg_message)
    return columns, func


def include_axis(op_name: Literal["agg", "apply"], colg: Series | DataFrame) -> bool:
    return isinstance(colg, ABCDataFrame) or (
        isinstance(colg, ABCSeries) and op_name == "agg"
    )

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Supply at least one kwarg in the named-aggregation form: df.agg(name=('col','sum')).
2. If you intended a positional func, pass it positionally instead of via kwargs: df.agg('sum').
3. Guard dynamic spec construction: if not spec: skip the agg call or supply a default like 'sum'.

Example fix

// before
spec = {}
df.agg(**spec)
// after
spec = {'total': ('a','sum')}
df.agg(**spec)

if not kwargs:
    raise TypeError("named aggregation requires at least one kwarg; pass func positionally otherwise")

def named_agg_nonempty(kwargs: dict) -> bool:
    return bool(kwargs)

try:
    df.agg(**kwargs)
except TypeError as e:
    if "Must provide 'func' or named aggregation" in str(e):
        df.agg('sum')
    else:
        raise

When it happens

Trigger: Calling an internal code path that delegates to validate_func_kwargs with an empty kwargs dict, or df.agg(**{}) / df.agg() on a path where named aggregation is expected. Triggered at apply.py:2315-2317 when not columns.

Common situations: Programmatically building named-agg kwargs and ending up with an empty dict; refactoring that strips all kwargs; calling resample/window.agg() without arguments; passing a precomputed spec variable that resolved to {}.

Related errors

• Must provide 'func' or tuples of '(column, aggfunc).
• func is expected but received {} in **kwargs.
• cannot combine transform and aggregation operations
• cannot perform both aggregation and transformation operation
• nested renamer is not supported

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