pola-rs/polars · error · ValueError

`offset` input for `with_row_index` cannot be

Error message

`offset` input for `with_row_index` cannot be {issue}, got {offset}

What it means

LazyFrame.with_row_index() validates `offset` at the engine boundary; an OverflowError from the Rust FFI (negative offset, or offset exceeding the maximum index value, e.g. beyond u32::MAX) is converted into this descriptive ValueError instead of a cryptic overflow.

Solutions

1. Ensure offset >= 0 and within the supported index range (check it against 2**32 - 1 or the documented maximum)
2. Clamp or validate the offset before the call
3. Use int(x) on numpy/pandas scalars to avoid odd overflow conversions

Example fix

// before
lf.with_row_index('idx', offset=-10)
// after
offset = max(0, computed_offset)
lf.with_row_index('idx', offset=offset)

MAX_OFFSET = 2**32 - 1
def safe_with_row_index(lf, name, offset):
    if offset is None:
        return lf.with_row_index(name)
    if not (0 <= offset <= MAX_OFFSET):
        raise ValueError(f'offset must be 0..{MAX_OFFSET}, got {offset}')
    return lf.with_row_index(name, offset)

def offset_ok(offset) -> bool:
    return isinstance(offset, int) and 0 <= offset <= 2**32 - 1

try:
    out = lf.with_row_index('idx', offset)
except ValueError as e:
    if '`offset` input for `with_row_index`' in str(e):
        offset = max(0, offset)
        out = lf.with_row_index('idx', offset)
    else:
        raise

When it happens

Trigger: Calling lf.with_row_index(name, offset=-1) or with an offset greater than the maximum allowed index value (2^32 - 1 on typical builds); the message dynamically states whether the value was negative or too large.

Common situations: Using negative offsets borrowed from slice semantics; computing offset from external data that can be negative or huge; passing numpy integers that overflow when converted.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• invalid plan stage
• `limit` cannot be None. If you want to show the complete…
• accessing ` ` from the top-level `polars` module was…
• altair>=5.4.0 is required for `.plot`
• `arctan2` expected a `str` or `Expr` got a

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/5308d076d2b9e087. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/lazyframe/frame.py:7238

        ...     pl.all(),
        ... ).collect()
        shape: (3, 3)
        ┌───────┬─────┬─────┐
        │ index ┆ a   ┆ b   │
        │ ---   ┆ --- ┆ --- │
        │ u32   ┆ i64 ┆ i64 │
        ╞═══════╪═════╪═════╡
        │ 0     ┆ 1   ┆ 2   │
        │ 1     ┆ 3   ┆ 4   │
        │ 2     ┆ 5   ┆ 6   │
        └───────┴─────┴─────┘
        """
        try:
            return self._from_pyldf(self._ldf.with_row_index(name, offset))
        except OverflowError:
            issue = "negative" if offset < 0 else "greater than the maximum index value"
            msg = f"`offset` input for `with_row_index` cannot be {issue}, got {offset}"
            raise ValueError(msg) from None

    def gather_every(self, n: int, offset: int = 0) -> LazyFrame:
        """
        Take every nth row in the LazyFrame and return as a new LazyFrame.

        .. engine-support:: in-memory, streaming

        Parameters
        ----------
        n
            Gather every *n*-th row.
        offset
            Starting index.

        Examples
        --------
        >>> lf = pl.LazyFrame(
        ...     {

View on GitHub (pinned to fe841f959e)