{"record":{"id":"5f3cd4c8477456cd","repo":"pola-rs/polars","slug":"invalid-type-for-on-columns-argument-qualified","errorCode":null,"errorMessage":"invalid type for `on_columns` argument: {qualified_type_name(on_columns)!r}","messagePattern":"invalid type for `on_columns` argument: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":8376,"sourceCode":"            elif aggregate_function == \"count\":\n                msg = \"use of `aggregate_function='count'` should be replaced with `aggregate_function='len'`.\"\n                raise ValueError(msg)\n            else:\n                msg = f\"invalid input for `aggregate_function` argument: {aggregate_function!r}\"\n                raise ValueError(msg)\n        elif aggregate_function is None:\n            agg = agg.item(allow_empty=True)\n        else:\n            agg = aggregate_function\n\n        on_cols: pl.DataFrame\n        if isinstance(on_columns, pl.DataFrame):\n            on_cols = on_columns\n        elif isinstance(on_columns, pl.Series):\n            on_cols = on_columns.to_frame()\n        elif isinstance(on_columns, str):\n            msg = f\"invalid type for `on_columns` argument: {qualified_type_name(on_columns)!r}\"\n            raise TypeError(msg)\n        else:\n            on_cols = pl.Series(values=on_columns).to_frame()\n\n        return self._from_pyldf(\n            self._ldf.pivot(\n                on=on_selector._pyselector,\n                on_columns=on_cols._df,\n                index=index_selector._pyselector,\n                values=values_selector._pyselector,\n                agg=agg._pyexpr,\n                maintain_order=maintain_order,\n                separator=separator,\n                column_naming=column_naming,\n            )\n        )\n\n    @removed_parameters(\n        RemovedParameter(name=\"streamable\", deprecated_in=\"1.5.0\", removed_in=\"2.0\")","sourceCodeStart":8358,"sourceCodeEnd":8394,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L8358-L8394","documentation":"Raised as a TypeError when the `on_columns` argument of LazyFrame.pivot is a plain string. This parameter expects a DataFrame, Series, or an iterable of values — a lone string is ambiguous and explicitly rejected.","triggerScenarios":"Calling `lf.pivot(on=..., on_columns=\"colname\")` — the isinstance chain (DataFrame, Series, str) hits the str branch and raises.","commonSituations":"Passing a single column name as a string by analogy with `on=`; mixing up the `on` and `on_columns` parameters.","solutions":["Wrap the string in a list: `on_columns=[\"colname\"]`.","Or pass a `pl.Series`/`pl.DataFrame` containing the desired values.","Use `on=` (a selector) instead if that was the intended parameter."],"exampleFix":"// before\nlf.pivot(on=\"date\", on_columns=\"region\")\n// after\nlf.pivot(on=\"date\", on_columns=[\"region\"])","handlingStrategy":"type-guard","validationCode":"if isinstance(on_columns, str):\n    on_columns = [on_columns]\nout = lf.pivot(on=on, on_columns=on_columns)","typeGuard":"def is_pivot_on_columns(v) -> bool:\n    return isinstance(v, (pl.DataFrame, pl.Series, list, tuple)) and not isinstance(v, str)","tryCatchPattern":"try:\n    out = lf.pivot(on=on, on_columns=on_columns)\nexcept TypeError as e:\n    if \"on_columns\" in str(e):\n        out = lf.pivot(on=on, on_columns=[on_columns])\n    else:\n        raise","preventionTips":["Never pass a bare string to on_columns; wrap in a list.","Distinguish `on` (selector) from `on_columns` (values container) in helpers.","Type-hint on_columns as Sequence[str] | pl.Series | pl.DataFrame in wrapper code."],"tags":["python","polars","pivot","type-error","argument-type"],"backgroundTag":"invalid-argument-value","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}