{"record":{"id":"482745352ef24fe1","repo":"pola-rs/polars","slug":"expected-by-predicate-to-be-an-expression-got","errorCode":null,"errorMessage":"expected `by_predicate` to be an expression, got {qualified_type_name(by_predicate)!r}","messagePattern":"expected `by_predicate` to be an expression, got (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":11878,"sourceCode":"                raise ValueError(msg)\n        elif index is not None and by_predicate is not None:\n            msg = \"cannot set both 'index' and 'by_predicate'; mutually exclusive\"\n            raise ValueError(msg)\n        elif isinstance(index, pl.Expr):\n            msg = \"expressions should be passed to the `by_predicate` parameter\"\n            raise TypeError(msg)\n\n        if index is not None:\n            row = self._df.row_tuple(index)\n            if named:\n                return dict(zip(self.columns, row, strict=True))\n            else:\n                return row\n\n        elif by_predicate is not None:\n            if not isinstance(by_predicate, pl.Expr):\n                msg = f\"expected `by_predicate` to be an expression, got {qualified_type_name(by_predicate)!r}\"\n                raise TypeError(msg)\n            rows = self.filter(by_predicate).rows()\n            n_rows = len(rows)\n            if n_rows > 1:\n                msg = f\"predicate <{by_predicate!s}> returned {n_rows} rows\"\n                raise TooManyRowsReturnedError(msg)\n            elif n_rows == 0:\n                msg = f\"predicate <{by_predicate!s}> returned no rows\"\n                raise NoRowsReturnedError(msg)\n\n            row = rows[0]\n            if named:\n                return dict(zip(self.columns, row, strict=True))\n            else:\n                return row\n        else:\n            msg = \"one of `index` or `by_predicate` must be set\"\n            raise ValueError(msg)\n","sourceCodeStart":11860,"sourceCodeEnd":11896,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L11860-L11896","documentation":"DataFrame.row's `by_predicate` parameter only accepts a pl.Expr — the whole boolean predicate, not a column name, list of names, or Series. Unlike selection APIs where strings are auto-converted to columns, row() requires the caller to supply the complete expression, so anything else raises TypeError with the qualified type name.","triggerScenarios":"df.row(by_predicate='a'); df.row(by_predicate=('a', 'b')); df.row(by_predicate=pl.Series([True, False])); passing a string column name or a boolean mask instead of pl.col(...) == value.","commonSituations":"Expecting pandas-like boolean-mask indexing; passing just the column name hoping row() infers 'where this column is true'; converting dict/kwargs-based filter specs into row() calls.","solutions":["Build the full expression: df.row(by_predicate=pl.col('flag')) for a boolean column, or df.row(by_predicate=pl.col('id') == 42) for a comparison","Combine conditions with & / | on expressions, not by passing multiple values","If you have a boolean mask Series, filter first: df.filter(mask).row(0) — or rebuild it as an expression"],"exampleFix":"# before\nrow = df.row(by_predicate='id')  # or by_predicate=my_mask_series\n\n# after\nrow = df.row(by_predicate=pl.col('id') == 42)","handlingStrategy":"type-guard","validationCode":"from polars.expr import Expr\n\nif not isinstance(by_predicate, Expr):\n    raise TypeError(f'by_predicate must be a full pl.Expr, got {type(by_predicate)!r}; e.g. pl.col(id_col) == value')\nrow = df.row(by_predicate=by_predicate)","typeGuard":"from polars.expr import Expr\n\ndef is_row_predicate(v: object) -> bool:\n    return isinstance(v, Expr)","tryCatchPattern":null,"preventionTips":["Always pass a complete expression (pl.col(...) == value), never a bare column name or mask","Wrap boolean-mask-style inputs: convert masks to filters (df.filter(mask).row(0))","Type-annotate by_predicate parameters as pl.Expr in your own wrappers"],"tags":["polars","dataframe","row","typeerror","expression","type-validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}