pola-rs/polars · error · ValueError

index positions should be greater than or equal to -2^32

Error message

index positions should be greater than or equal to -2^32

What it means

Companion of the upper-bound check in _convert_series_to_indices (getitem.py:374): with the default UInt32 index backend, an Int64 Series whose minimum is < -2**32 cannot be represented (negative positions are resolved against frame height) and raises this ValueError.

Source

Thrown at py-polars/src/polars/_utils/getitem.py:374

        return s

    if not s.dtype.is_integer():
        if s.dtype == Boolean:
            _raise_on_boolean_mask()
        else:
            msg = f"cannot treat Series of type {s.dtype} as indices"
            raise TypeError(msg)

    if s.len() == 0:
        return pl.Series(s.name, [], dtype=idx_type)

    if idx_type == UInt32:
        if s.dtype in {Int64, UInt64} and s.max() >= U32_MAX:  # type: ignore[operator]
            msg = "index positions should be smaller than 2^32"
            raise ValueError(msg)
        if s.dtype == Int64 and s.min() < -U32_MAX:  # type: ignore[operator]
            msg = "index positions should be greater than or equal to -2^32"
            raise ValueError(msg)

    if s.dtype.is_signed_integer():
        if s.min() < 0:  # type: ignore[operator]
            if idx_type == UInt32:
                idxs = s.cast(Int32) if s.dtype in {Int8, Int16} else s
            else:
                idxs = s.cast(Int64) if s.dtype in {Int8, Int16, Int32} else s

            # Update negative indexes to absolute indexes.
            return (
                idxs.to_frame()
                .select(
                    F.when(F.col(idxs.name) < 0)
                    .then(size + F.col(idxs.name))
                    .otherwise(F.col(idxs.name))
                    .cast(idx_type)
                )
                .to_series(0)

View on GitHub (pinned to df599052da)

Solutions

1. Fix the negative values: valid row positions must satisfy -df.height <= i < df.height
2. Drop or clamp sentinels before indexing: idx = idx.filter(idx >= -df.height)
3. Install polars-u64-idx if the large negative values are legitimate in your pipeline

Example fix

# before
df[pl.Series([-5_000_000_000], dtype=pl.Int64)]

# after
df[pl.Series([-1], dtype=pl.Int64)]  # valid negative offset within height

if idx.dtype == pl.Int64 and idx.len() and idx.min() < -(2**32):
    raise ValueError("negative positions below -2^32 are invalid")
df[idx]

def above_neg_u32_floor(s: "pl.Series") -> bool:
    return not (s.dtype == pl.Int64 and s.len() and (s.min() if s.min() is not None else 0) < -(2**32))

When it happens

Trigger: df[pl.Series([-(2**32) - 1], dtype=pl.Int64)]; sentinel values like -9999999999 in an index column; arithmetic that produces very large negative offsets.

Common situations: Sentinel/fill values (-1 padded to 64-bit extremes) leaking into index Series; bugs computing relative offsets far outside the frame height.

Related errors

• index positions should be smaller than 2^32
• cannot treat Series of type {s.dtype} as indices
• only 1D NumPy arrays can be treated as indices
• cannot treat NumPy array of type {arr.dtype} as indices
• Can't patch loop of type %s

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