pola-rs/polars · error · ValueError

can only call '.item()' if the Series is of length 1, or an

Error message

can only call '.item()' if the Series is of length 1, or an explicit index is provided (Series is of length {len(self)})

What it means

Item-extraction guard: .item() without an explicit index requires the Series to have exactly one element; a longer Series triggers the error unless an index is passed. Fires on any multi-row Series with index=None.

Source

Thrown at py-polars/src/polars/series/series.py:1656

        If no index is provided, this is equivalent to `s[0]`, with a check
        that the shape is (1,). With an index, this is equivalent to `s[index]`.

        Examples
        --------
        >>> s1 = pl.Series("a", [1])
        >>> s1.item()
        1
        >>> s2 = pl.Series("a", [9, 8, 7])
        >>> s2.cum_sum().item(-1)
        24
        """
        if index is None:
            if len(self) != 1:
                msg = (
                    "can only call '.item()' if the Series is of length 1,"
                    f" or an explicit index is provided (Series is of length {len(self)})"
                )
                raise ValueError(msg)
            return self._s.get_index(0)

        return self._s.get_index_signed(index)

    def estimated_size(self, unit: SizeUnit = "b") -> int | float:
        """
        Return an estimation of the total (heap) allocated size of the Series.

        Estimated size is given in the specified unit (bytes by default).

        This estimation is the sum of the size of its buffers, validity, including
        nested arrays. Multiple arrays may share buffers and bitmaps. Therefore, the
        size of 2 arrays is not the sum of the sizes computed from this function. In
        particular, [`StructArray`]'s size is an upper bound.

        When an array is sliced, its allocated size remains constant because the buffer
        unchanged. However, this function will yield a smaller number. This is because
        this function returns the visible size of the buffer, not its total capacity.

View on GitHub (pinned to 68506541d2)

Solutions

1. Either reduce the Series to length 1 first (e.g. `s.filter(...)`), or pass an explicit index: `s.item(0)`.

When it happens

Trigger: Thrown at py-polars/src/polars/series/series.py:1771 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-19). Data as JSON: /api/errors/b52357e632bd4a7b. Report an issue: GitHub.