{"record":{"id":"b71e113ace48f7bd","repo":"pola-rs/polars","slug":"can-only-call-row-without-index-or-by-pred","errorCode":null,"errorMessage":"can only call `.row()` without \"index\" or \"by_predicate\" values if the DataFrame has a single row; shape={self.shape!r}","messagePattern":"can only call `\\.row\\(\\)` without \"index\" or \"by_predicate\" values if the DataFrame has a single row; shape=(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":11860,"sourceCode":"        names to row values.\n\n        >>> df.row(2, named=True)\n        {'foo': 3, 'bar': 8, 'ham': 'c'}\n\n        Use `by_predicate` to return the row that matches the given predicate.\n\n        >>> df.row(by_predicate=(pl.col(\"ham\") == \"b\"))\n        (2, 7, 'b')\n        \"\"\"\n        if index is None and by_predicate is None:\n            if self.height == 1:\n                index = 0\n            else:\n                msg = (\n                    'can only call `.row()` without \"index\" or \"by_predicate\" values '\n                    f\"if the DataFrame has a single row; shape={self.shape!r}\"\n                )\n                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)","sourceCodeStart":11842,"sourceCodeEnd":11878,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L11842-L11878","documentation":"DataFrame.row(index=None, by_predicate=None) returns a single row; calling it with no arguments is only allowed when the frame has exactly one row (then that row is returned via index=0). On any other height the choice of 'the' row is ambiguous, so polars raises ValueError and includes the frame's shape in the message.","triggerScenarios":"df.row() where df.height != 1: multi-row frames (most common), empty frames (height 0), or frames after unique/filter/group_by-head operations that unexpectedly changed cardinality.","commonSituations":"Fetching 'the' row after filtering on what was assumed to be a unique key (config/version lookups, ID fetch) when duplicates actually exist; calling row() on an empty result set; using row() on output of a search helper that can return several hits.","solutions":["Pass an explicit selector: df.row(index=0) for the first row, or df.row(by_predicate=pl.col('id') == value) for a key match","Guard the call when single-row is the expectation: if df.height == 1: row = df.row()","If multiple matches are legitimate, take one deterministically: df.filter(pred).head(1).row(0), or use .rows() for all of them","For key lookups, assert uniqueness first: assert df.filter(pl.col('id') == value).height == 1"],"exampleFix":"# before\nrow = df.row()  # ValueError when df.height != 1\n\n# after\nrow = df.row(by_predicate=pl.col('id') == 42)\n# or\nrow = df.row(0)  # explicit first row","handlingStrategy":"validation","validationCode":"if df.height != 1:\n    raise ValueError(f'expected exactly one row, got {df.height}')\nrow = df.row()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer explicit selectors (df.row(0) or df.row(by_predicate=...)) over the bare df.row()","Assert df.height == 1 before bare row() calls on filtered/looked-up frames","In helpers, branch on height: 0 -> not found, >1 -> ambiguous, 1 -> df.row()"],"tags":["polars","dataframe","row","cardinality","valueerror","lookup"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}