What causes "Named aggregation is not supported when {axis=}." in pandas-dev/pandas?

Remove named aggregation when using axis=1: use a plain function or list of functions instead.

pandas-dev/pandas · error · NotImplementedError

Named aggregation is not supported when

Error message

Named aggregation is not supported when {axis=}.

What it means

Named aggregation (e.g., df.agg(result=('col', 'func'))) is a syntax that assigns output column names. It is only supported when aggregating along axis=0 (the default, operating on columns). When axis=1 is specified (row-wise operation), named aggregation is not implemented and raises NotImplementedError. The f-string uses {axis=} which produces 'axis=1' in the message.

Solutions

Remove named aggregation when using axis=1: use a plain function or list of functions instead.
If you need named output with row-wise operations, apply first, then rename: df.apply(func, axis=1).rename(columns=...).
Use axis=0 (default) if named aggregation is important to your workflow.

Example fix

# before
df.agg(result=('col', 'mean'), axis=1)

# after — use a plain function for row-wise operations
df.apply(lambda row: row['col'].mean(), axis=1)

Defensive patterns

Strategy: validation

Validate before calling

def safe_agg(df, axis=0, **kwargs):
    # Check for named aggregation kwargs with axis=1
    if axis == 1 and any(isinstance(v, tuple) and len(v) == 2 for v in kwargs.values()):
        raise NotImplementedError(
            "Named aggregation is not supported with axis=1; use axis=0 or plain functions"
        )
    return df.agg(axis=axis, **kwargs)

Type guard

def uses_named_aggregation(kwargs) -> bool:
    return any(isinstance(v, tuple) for v in kwargs.values())

Try / catch

try:
    result = df.agg(new_name=('col', 'mean'), axis=1)
except NotImplementedError as e:
    if "Named aggregation" in str(e):
        result = df.apply(lambda row: row['col'].mean(), axis=1)
    else:
        raise

Prevention

Never combine named aggregation kwargs with axis=1.
Use axis=0 (default) for named aggregation, or use plain functions with axis=1.
Remember the named aggregation syntax: df.agg(output=(input_col, func)).

When it happens

Trigger: Calling df.agg(new_name=('col', 'mean'), axis=1) — using named aggregation kwargs with axis=1. Calling df.apply(...) or df.agg(...) with a dict-like func that includes column assignments and axis=1 simultaneously.

Common situations: Trying to apply column-name-preserving aggregation row-wise. Adapting an axis=0 named-aggregation call to axis=1 by just changing the axis parameter. Confusing the semantics of axis=1 (row-wise apply) with named column output.

Related errors

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

Appendix: source

Thrown at pandas/core/apply.py:246

    axis: Axis = 0,
    raw: bool = False,
    result_type: str | None = None,
    by_row: Literal[False, "compat"] = "compat",
    engine: str = "python",
    engine_kwargs: dict[str, bool] | None = None,
    args=None,
    kwargs=None,
) -> FrameApply:
    """construct and return a row or column based frame apply object"""
    _, func, columns, _ = reconstruct_func(func, **kwargs)

    axis = obj._get_axis_number(axis)
    klass: type[FrameApply]
    if axis == 0:
        klass = FrameRowApply
    elif axis == 1:
        if columns:
            raise NotImplementedError(
                f"Named aggregation is not supported when {axis=}."
            )
        klass = FrameColumnApply

    return klass(
        obj,
        func,
        raw=raw,
        result_type=result_type,
        by_row=by_row,
        engine=engine,
        engine_kwargs=engine_kwargs,
        args=args,
        kwargs=kwargs,
    )


class Apply(metaclass=abc.ABCMeta):

View on GitHub (pinned to 3b7651241d)