pola-rs/polars · error · ValueError

cannot call `.item()` with only one of `row` or `column`

Error message

cannot call `.item()` with only one of `row` or `column`

What it means

Raised by DataFrame.item() when exactly one of `row` and `column` is provided. The accessor contract is all-or-nothing: with no arguments it requires a 1x1 frame, and with both arguments it fetches a specific cell. A single argument is ambiguous (row of what? column of what?), so polars rejects it immediately rather than guessing a convention.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:1738

        >>> df.select((pl.col("a") * pl.col("b")).sum()).item()
        32
        >>> df.item(1, 1)
        5
        >>> df.item(2, "b")
        6
        """
        if row is None and column is None:
            if self.shape != (1, 1):
                msg = (
                    'can only call `.item()` without "row" or "column" values if the '
                    f"DataFrame has a single element; shape={self.shape!r}"
                )
                raise ValueError(msg)
            return self._df.to_series(0).get_index(0)

        elif row is None or column is None:
            msg = "cannot call `.item()` with only one of `row` or `column`"
            raise ValueError(msg)

        s = (
            self._df.to_series(column)
            if isinstance(column, int)
            else self._df.get_column(column)
        )
        return s.get_index_signed(row)

    @deprecate_renamed_parameter("future", "compat_level", version="1.1")
    def to_arrow(self, *, compat_level: CompatLevel | None = None) -> pa.Table:
        """
        Collect the underlying arrow arrays in an Arrow Table.

        This operation is mostly zero copy.

        Data types that do copy:
            - CategoricalType

View on GitHub (pinned to df599052da)

Solutions

1. Pass both arguments: `df.item(row, column)` with column as int index or name string
2. If you want a whole row, use `df.row(index)`; if you want a whole column, `df[column, row]` or `df.get_column(name)[row]`
3. If you meant the single element of a 1x1 frame, call `df.item()` with no arguments

Example fix

# before
v = df.item(0)          # only row given

# after
v = df.item(0, 'col')   # row and column
# or the whole row:
row = df.row(0)

if (row is None) != (column is None):
    raise ValueError('.item() needs both row and column, or neither')
value = df.item(row, column)

def item_args_ok(row: int | None, column: int | str | None) -> bool:
    """Both None or both set — anything else makes .item() ambiguous."""
    return (row is None) == (column is None)

try:
    v = df.item(row, column)
except ValueError as e:
    if 'only one of' in str(e):
        v = df.row(row) if column is None else df.get_column(column).to_list()
    else:
        raise

When it happens

Trigger: `df.item(row=0)`, `df.item(None, 'col')`, `df.item(2)`, or `df.item(column='a')` — any call where precisely one of the two optional parameters is not None.

Common situations: Copy-paste from pandas `df.item()` habits mixed with `.iat[row, col]` muscle memory; refactoring code that used `df['col'][row]` into `.item()` and forgetting the second argument; passing row=None as a 'default' meaning 'any row'.

Related errors

• can only call `.item()` without "row" or "column" values if
• the given column-schema names do not match the data dictiona
• Pandas dataframe contains non-unique indices and/or column n
• Pandas indices and column names must not overlap.
• dimensions of columns arg must match data dimensions

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/34ca96339088561b. Report an issue: GitHub.