pandas-dev/pandas · error · TypeError

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

Error message

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

What it means

TypeError raised in validate_func_kwargs when no kwargs at all are passed to a code path that requires named aggregation. With no columns and no funcs the aggregation cannot proceed.

Solutions

1. Ensure at least one column->function entry exists in kwargs before calling.
2. Fall back to a positional func when the kwargs dict is empty.
3. Guard upstream: if not kwargs: return early or use a default function.

Example fix

# before
df.agg(**{})
# after
df.agg('sum')

def safe_named_agg(obj, kwargs):
    if not kwargs:
        raise ValueError('named aggregation requires at least one column->func entry')
    return obj.agg(**kwargs)

try:
    df.agg(**kwargs)
except TypeError as e:
    if 'named aggregation' in str(e):
        df.agg('sum')  # fallback
    else:
        raise

When it happens

Trigger: Internal callers reaching validate_func_kwargs with an empty kwargs dict; df.agg(**{}) style invocations; selecting an aggregation spec that resolves to no columns.

Common situations: Dynamic code that builds kwargs from a dict comprehension which can yield nothing when the input list is empty.

Related errors

• func is expected but received
• Label(s) do not exist
• Must provide 'func' or tuples of '(column, aggfunc).
• Named aggregation is not supported when
• axis other than 0 is not supported

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

Appendix: 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 3b7651241d)