pola-rs/polars · error · ValueError

invalid input for `aggregate_function` argument

Error message

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

What it means

Raised as a ValueError when `aggregate_function` is a string that is not one of the supported names ('first', 'item', 'last', 'len'). Unknown strings are rejected up front rather than failing during execution.

Solutions

Use one of the supported string values: 'first', 'item', 'last', or 'len'.
For other aggregations, pass an expression instead, e.g. `aggregate_function=pl.element().sum()`.
Fix typos — the message echoes the offending value.

Example fix

// before
lf.pivot(on="date", index="id", values="sales", aggregate_function="sum")
// after
lf.pivot(on="date", index="id", values="sales", aggregate_function=pl.element().sum())

Defensive patterns

Strategy: validation

Validate before calling

_ALLOWED = {"first", "item", "last", "len"}
if isinstance(aggregate_function, str) and aggregate_function not in _ALLOWED:
    raise ValueError(f"aggregate_function must be one of {sorted(_ALLOWED)}")

Try / catch

try:
    out = lf.pivot(on=on, index=idx, values=vals, aggregate_function=agg)
except ValueError as e:
    if "invalid input for `aggregate_function`" in str(e):
        out = lf.pivot(on=on, index=idx, values=vals, aggregate_function="len")
    else:
        raise

Prevention

Only use documented string names: first, item, last, len.
Prefer passing an expression (pl.element().sum(), etc.) for anything else.
Add a test enumerating allowed aggregate_function values.

When it happens

Trigger: Calling `lf.pivot(..., aggregate_function="sum")` or any misspelled/unsupported string like "mean", "Count", or "lenght".

Common situations: Translating pandas pivot_table aggfunc names ('sum', 'mean') directly to polars; typos in the aggregation name.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

                agg = agg.sum()
            elif aggregate_function == "max":
                agg = agg.max()
            elif aggregate_function == "min":
                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":
                msg = "use of `aggregate_function='count'` should be replaced with `aggregate_function='len'`."
                raise ValueError(msg)
            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 fe841f959e)