pola-rs/polars · error · ValueError

invalid input for `aggregate_function` argument: {aggregate_

Error message

invalid input for `aggregate_function` argument: {aggregate_function!r}

What it means

LazyFrame.pivot()'s aggregate_function, when passed as a string, must be one of 'first', 'last', 'item', 'sum', 'len', 'min', 'max' (plus deprecated 'count' which maps to 'len'). Any other string raises ValueError. Alternatively pass None (requires unique combinations) or an actual pl.Expr for custom aggregation.

Source

Thrown at py-polars/src/polars/lazyframe/frame.py:8682

                agg = agg.min()
            elif aggregate_function == "mean":
                agg = agg.mean()
            elif aggregate_function == "median":
                agg = agg.median()
            elif aggregate_function == "last":
                agg = agg.last()
            elif aggregate_function == "len":
                agg = agg.len()
            elif aggregate_function == "count":
                issue_deprecation_warning(
                    "`aggregate_function='count'` input for `pivot` is deprecated."
                    " Please use `aggregate_function='len'`.",
                    version="0.20.5",
                )
                agg = agg.len()
            else:
                msg = f"invalid input for `aggregate_function` argument: {aggregate_function!r}"
                raise ValueError(msg)
        elif aggregate_function is None:
            agg = agg.item(allow_empty=True)
        else:
            agg = aggregate_function

        on_cols: pl.DataFrame
        if isinstance(on_columns, pl.DataFrame):
            on_cols = on_columns
        elif isinstance(on_columns, pl.Series):
            on_cols = on_columns.to_frame()
        elif isinstance(on_columns, str):
            msg = f"invalid type for `on_columns` argument: {qualified_type_name(on_columns)!r}"
            raise TypeError(msg)
        else:
            on_cols = pl.Series(values=on_columns).to_frame()

        return self._from_pyldf(
            self._ldf.pivot(

View on GitHub (pinned to df599052da)

Solutions

1. Use one of the allowed strings: 'first', 'last', 'item', 'sum', 'min', 'max', 'len'
2. For 'mean'-style aggregation not in the list, pass a pl.Expr: aggregate_function=pl.element().mean()
3. Replace 'count' with 'len' (count is deprecated)
4. Validate config values against the allowed set before calling pivot

Example fix

# before
wide = lf.pivot(on='month', index='id', aggregate_function='mean')

# after
import polars as pl
wide = lf.pivot(on='month', index='id', aggregate_function=pl.element().mean())

ALLOWED = {'first', 'last', 'item', 'sum', 'min', 'max', 'len'}
if isinstance(aggregate_function, str) and aggregate_function not in ALLOWED:
    raise ValueError(f'unsupported aggregate_function: {aggregate_function!r}')
lf.pivot(on=on, index=index, aggregate_function=aggregate_function)

def is_supported_pivot_agg(agg) -> bool:
    import polars as pl
    allowed = {'first', 'last', 'item', 'sum', 'min', 'max', 'len'}
    return agg is None or (isinstance(agg, str) and agg in allowed) or isinstance(agg, pl.Expr)

When it happens

Trigger: lf.pivot(..., aggregate_function='mean') — 'mean' is not in the allowed set; passing 'avg', 'median', or a function name from another library (e.g. numpy or pandas agg strings like 'size'); typos like 'Sum'.

Common situations: Developers assuming pandas .agg() string vocabulary carries over; dynamic aggregation selection from user config; older code using 'count' (deprecated but still works with a warning).

Related errors

• negative stop is not supported for lazy slices
• negative stride is not supported in conjunction with start+s
• the given slice {s!r} is not supported by lazy computation\n
• LazyFrame `how` must be one of {{{allowed}}}, got {how!r}
• `format` must be one of {'binary', 'json'}, got {format!r}

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/6d59ff093ac8f31f. Report an issue: GitHub.