pola-rs/polars · info

one of `index` or `by_predicate` must be set

Error message

one of `index` or `by_predicate` must be set

What it means

A defensive ValueError at the end of DataFrame.row's dispatch chain, raised if the method reaches row extraction with neither `index` nor `by_predicate` set. In the current implementation this branch is effectively unreachable through the public API: the both-None case is fully handled by the first branch (height == 1 -> index = 0, otherwise the 'single row' error). It exists to make the function total and to catch future signature changes or reflective/monkey-patched calls that bypass the normal entry conditions.

Source

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

                msg = f"expected `by_predicate` to be an expression, got {qualified_type_name(by_predicate)!r}"
                raise TypeError(msg)
            rows = self.filter(by_predicate).rows()
            n_rows = len(rows)
            if n_rows > 1:
                msg = f"predicate <{by_predicate!s}> returned {n_rows} rows"
                raise TooManyRowsReturnedError(msg)
            elif n_rows == 0:
                msg = f"predicate <{by_predicate!s}> returned no rows"
                raise NoRowsReturnedError(msg)

            row = rows[0]
            if named:
                return dict(zip(self.columns, row, strict=True))
            else:
                return row
        else:
            msg = "one of `index` or `by_predicate` must be set"
            raise ValueError(msg)

    @overload
    def rows(self, *, named: Literal[False] = ...) -> list[tuple[Any, ...]]: ...

    @overload
    def rows(self, *, named: Literal[True]) -> list[dict[str, Any]]: ...

    def rows(
        self, *, named: bool = False
    ) -> list[tuple[Any, ...]] | list[dict[str, Any]]:
        """
        Returns all data in the DataFrame as a list of rows of python-native values.

        By default, each row is returned as a tuple of values given in the same order
        as the frame columns. Setting `named=True` will return rows of dictionaries
        instead.

        Parameters

View on GitHub (pinned to df599052da)

Solutions

1. Pass an explicit selector (index=0 or by_predicate=pl.col(...)) — this also future-proofs the call
2. Check for monkey-patches or subclasses overriding row() in your codebase
3. If it reproduces on stock polars, report it as a bug with a minimal reproducer

if index is None and by_predicate is None and df.height != 1:
    raise ValueError(f'row() needs index or by_predicate; frame shape is {df.shape}')
row = df.row(index=index, by_predicate=by_predicate)

When it happens

Trigger: Not producible by normal calls to DataFrame.row in this version; conceivable only via reflection, monkey-patching the method, or a future polars version that alters the early branches while keeping this fallback.

Common situations: Effectively none in practice — if you see this error, suspect a patched/overridden row method or a non-standard polars build; otherwise treat it as an internal invariant violation worth reporting upstream.

Related errors

• can only call `.row()` without "index" or "by_predicate" val
• cannot set both 'index' and 'by_predicate'; mutually exclusi
• invalid `return_type`; found {return_type!r}, expected one o
• `offset` input for `with_row_index` cannot be {issue}, got {
• cannot use `partition_by` with `maintain_order=False, includ

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