{"record":{"id":"37c43f2c12464c86","repo":"pola-rs/polars","slug":"expected-polars-expression-or-object-convertible-t","errorCode":null,"errorMessage":"Expected Polars expression or object convertible to one, got {type(value)}.\n\nHint: if you tried\n    group_by(by={value!r})\nthen you probably want to use this instead:\n    group_by({value!r})","messagePattern":"Expected Polars expression or object convertible to one, got (.+?)\\.\n\nHint: if you tried\n    group_by\\(by=(.+?)\\)\nthen you probably want to use this instead:\n    group_by\\((.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":7313,"sourceCode":"        shape: (1, 3)\n        ┌─────┬─────┬─────┐\n        │ a   ┆ b   ┆ c   │\n        │ --- ┆ --- ┆ --- │\n        │ str ┆ i64 ┆ i64 │\n        ╞═════╪═════╪═════╡\n        │ c   ┆ 3   ┆ 1   │\n        └─────┴─────┴─────┘\n        \"\"\"\n        for value in named_by.values():\n            if not isinstance(value, (str, pl.Expr, pl.Series)):\n                msg = (\n                    f\"Expected Polars expression or object convertible to one, got {type(value)}.\\n\\n\"\n                    \"Hint: if you tried\\n\"\n                    f\"    group_by(by={value!r})\\n\"\n                    \"then you probably want to use this instead:\\n\"\n                    f\"    group_by({value!r})\"\n                )\n                raise TypeError(msg)\n        return GroupBy(\n            self, *by, **named_by, maintain_order=maintain_order, predicates=None\n        )\n\n    @deprecate_renamed_parameter(\"by\", \"group_by\", version=\"0.20.14\")\n    def rolling(\n        self,\n        index_column: IntoExpr,\n        *,\n        period: str | timedelta,\n        offset: str | timedelta | None = None,\n        closed: ClosedInterval = \"right\",\n        group_by: IntoExpr | Iterable[IntoExpr] | None = None,\n    ) -> RollingGroupBy:\n        \"\"\"\n        Create rolling groups based on a temporal or integer column.\n\n        Different from a `group_by_dynamic` the windows are now determined by the","sourceCodeStart":7295,"sourceCodeEnd":7331,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L7295-L7331","documentation":"DataFrame.group_by(*by, **named_by) accepts positional grouping keys plus keyword 'named' expressions. Every value reaching it — positional or keyword — must be a str, pl.Expr, or pl.Series; anything else raises TypeError. The most common cause is df.group_by(by={...}) or df.group_by(by=[...]): `by` is not a named parameter of this method, so Python captures it into **named_by, and the error embeds a Hint showing the exact rewrite for that case.","triggerScenarios":"df.group_by(by=['a', 'b']) or df.group_by(by={'a': 1}) (the by= keyword lands in named_by as a list/dict); df.group_by(grp=<numpy array or pandas object>) passing a non-polars object as a named key.","commonSituations":"Translating pandas df.groupby(by=...) to polars; assuming group_by accepts keyword containers like join/pivot do; IDE autocompletion inserting by=; forwarding kwargs from a generic wrapper into group_by.","solutions":["Pass grouping keys positionally or as one iterable: df.group_by('a', 'b') or df.group_by(['a', 'b'])","For a named expression use a keyword with an Expr value: df.group_by(dept=pl.col('department'))","Convert foreign objects first (numpy array -> pl.Series) or reference the column by name instead of passing raw data","Read the Hint in the message — it states verbatim: use group_by(<your value>) instead of group_by(by=<your value>)"],"exampleFix":"# before\nresult = df.group_by(by=['a', 'b']).agg(pl.len())\n\n# after\nresult = df.group_by(['a', 'b']).agg(pl.len())  # or df.group_by('a', 'b')","handlingStrategy":"type-guard","validationCode":"from polars.expr import Expr\nfrom polars.series import Series\n\nfor v in list(by) + list(named_by.values()):\n    if not isinstance(v, (str, Expr, Series)):\n        raise TypeError(f'group_by key must be str/Expr/Series, got {type(v)!r}')","typeGuard":"from polars.expr import Expr\nfrom polars.series import Series\n\ndef is_group_by_key(v: object) -> bool:\n    return isinstance(v, (str, Expr, Series))","tryCatchPattern":"try:\n    gb = df.group_by(*by, **named)\nexcept TypeError as e:\n    if 'group_by' not in str(e):\n        raise\n    # follow the embedded Hint: pass the value positionally\n    gb = df.group_by(list(by) + list(named.values()))","preventionTips":["Never write group_by(by=...) — there is no `by` keyword; pass keys positionally or as one list","Type-annotate helpers that forward grouping keys as IntoExpr | str | Series","Convert numpy/pandas objects to pl.Series or column names at your API boundary"],"tags":["polars","dataframe","group-by","typeerror","pandas-migration","kwargs"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}