{"record":{"id":"46b4cd256c3730ae","repo":"pola-rs/polars","slug":"can-only-call-item-without-row-or-column","errorCode":null,"errorMessage":"can only call `.item()` without \"row\" or \"column\" values if the DataFrame has a single element; shape={self.shape!r}","messagePattern":"can only call `\\.item\\(\\)` without \"row\" or \"column\" values if the DataFrame has a single element; shape=(.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":1733,"sourceCode":"        the shape is (1,1). With row/col, this is equivalent to `df[row,col]`.\n\n        Examples\n        --------\n        >>> df = pl.DataFrame({\"a\": [1, 2, 3], \"b\": [4, 5, 6]})\n        >>> df.select((pl.col(\"a\") * pl.col(\"b\")).sum()).item()\n        32\n        >>> df.item(1, 1)\n        5\n        >>> df.item(2, \"b\")\n        6\n        \"\"\"\n        if row is None and column is None:\n            if self.shape != (1, 1):\n                msg = (\n                    'can only call `.item()` without \"row\" or \"column\" values if the '\n                    f\"DataFrame has a single element; shape={self.shape!r}\"\n                )\n                raise ValueError(msg)\n            return self._df.to_series(0).get_index(0)\n\n        elif row is None or column is None:\n            msg = \"cannot call `.item()` with only one of `row` or `column`\"\n            raise ValueError(msg)\n\n        s = (\n            self._df.to_series(column)\n            if isinstance(column, int)\n            else self._df.get_column(column)\n        )\n        return s.get_index_signed(row)\n\n    @deprecate_renamed_parameter(\"future\", \"compat_level\", version=\"1.1\")\n    def to_arrow(self, *, compat_level: CompatLevel | None = None) -> pa.Table:\n        \"\"\"\n        Collect the underlying arrow arrays in an Arrow Table.\n","sourceCodeStart":1715,"sourceCodeEnd":1751,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L1715-L1751","documentation":"Raised by DataFrame.item() when called with no arguments on a frame whose shape is not exactly (1, 1). `.item()` is the numpy/antigravity-style accessor for 'the single element of this frame'; polars validates the shape up front because the return value is ambiguous for any other shape. The message includes the actual shape so you can immediately see whether you have too many rows or too many columns.","triggerScenarios":"`df.item()` on a 3x1 frame (e.g. a group_by().count() result that didn't reduce to one row), on a 1x2 frame, or on an empty frame. Any `.item()` without row/column arguments where `df.shape != (1, 1)`.","commonSituations":"Aggregations expected to return one row but returning many (e.g. forgot to filter, or group_by produced multiple groups); unique-count checks like `df.filter(...).select(pl.len()).item()` that unexpectedly yield 0 rows; reading config/lookup tables where duplicates or zero matches break the 1x1 assumption.","solutions":["Check the shape before calling: `if df.shape == (1, 1): v = df.item()`","Get the first element regardless of row count: `df[0, 0]`, `df.item(0, 0)`, or `df.row(0, named=True)`","Fix the upstream query so it provably returns one row: add `.filter(...)`, use `.unique()` on the grouping key, or assert row count with `pl.assert_frame`","For a 1xN frame use `df.row(0)` to get all values of the single row"],"exampleFix":"# before\nvalue = df.filter(pl.col('k') == key).select('v').item()\n\n# after\nsub = df.filter(pl.col('k') == key).select('v')\nvalue = sub.item(0, 0) if sub.height == 1 else None","handlingStrategy":"validation","validationCode":"if df.shape != (1, 1):\n    raise ValueError(f'expected single-cell frame, got {df.shape}')\nvalue = df.item()","typeGuard":"def is_single_cell(df: pl.DataFrame) -> bool:\n    \"\"\"True only for a 1x1 frame, the sole valid target of .item().\"\"\"\n    return df.shape == (1, 1)","tryCatchPattern":"try:\n    v = df.item()\nexcept ValueError as e:\n    if 'single element' in str(e):\n        v = df.item(0, 0)  # or handle multi-row case explicitly\n    else:\n        raise","preventionTips":["Assert row counts after aggregations expected to yield one row (e.g. sub.height == 1)","Prefer explicit df.item(0, 0) or df[0, 0] when you know the frame's shape","Include the frame's shape in your own error context to speed diagnosis"],"tags":["dataframe","item","shape-mismatch","validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}