pola-rs/polars · error

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

Error message

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

What it means

DataFrame.with_row_index(name, offset) adds a row counter starting at `offset`. The offset is converted to the internal unsigned index dtype (u32 in standard builds, u64 with the bigidx feature) on the Rust side; a value that cannot be represented — negative, or above the maximum for that integer type — raises OverflowError, which this wrapper re-raises as ValueError with a 'negative' or 'greater than the maximum index value' detail.

Source

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

        ...     pl.all(),
        ... )
        shape: (3, 3)
        ┌───────┬─────┬─────┐
        │ index ┆ a   ┆ b   │
        │ ---   ┆ --- ┆ --- │
        │ u32   ┆ i64 ┆ i64 │
        ╞═══════╪═════╪═════╡
        │ 0     ┆ 1   ┆ 2   │
        │ 1     ┆ 3   ┆ 4   │
        │ 2     ┆ 5   ┆ 6   │
        └───────┴─────┴─────┘
        """
        try:
            return self._from_pydf(self._df.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

    @deprecated(
        "`DataFrame.with_row_count` is deprecated; use `with_row_index` instead."
        " Note that the default column name has changed from 'row_nr' to 'index'."
    )
    def with_row_count(self, name: str = "row_nr", offset: int = 0) -> DataFrame:
        """
        Add a column at index 0 that counts the rows.

        .. deprecated:: 0.20.4
            Use the :meth:`with_row_index` method instead.
            Note that the default column name has changed from 'row_nr' to 'index'.

        Parameters
        ----------
        name
            Name of the column to add.
        offset

View on GitHub (pinned to df599052da)

Solutions

1. Use a non-negative offset that fits the index dtype (0 to 2**32-1 on standard builds)
2. For an arbitrary (including negative) start, add an expression instead: df.with_row_index('index').with_columns((pl.col('index') + start).alias('index')) — cast to Int64 if start is negative or large
3. Fix the arithmetic that produced the offset, e.g. clamp with max(0, total_so_far)
4. When continuing numbering across frames, accumulate offsets as a running total of preceding frame heights (always >= 0)

Example fix

# before
df = df.with_row_index('idx', offset=-10)

# after
df = (
    df.with_row_index('idx')
      .with_columns((pl.col('idx').cast(pl.Int64) - 10).alias('idx'))
)

MAX_OFFSET = 2**32 - 1  # standard u32 index builds; 2**64 - 1 with bigidx
if not (0 <= offset <= MAX_OFFSET):
    raise ValueError(f'offset {offset} out of range [0, {MAX_OFFSET}]')
df = df.with_row_index('index', offset=offset)

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

try:
    df = df.with_row_index('idx', offset)
except ValueError as e:
    if '`offset` input' not in str(e):
        raise
    # negative or out-of-range start: emulate via expression instead
    df = df.with_row_index('idx').with_columns((pl.col('idx').cast(pl.Int64) + offset).alias('idx'))

When it happens

Trigger: df.with_row_index('idx', offset=-1) (any negative offset); df.with_row_index('idx', offset=2**32) on a standard u32-index build; offsets computed as len(prev_frames) - len(df) that go negative; offsets sourced from configuration or a data file.

Common situations: Emulating SQL ROW_NUMBER() with a non-zero or negative start; continuing numbering across concatenated frames where an intermediate frame is longer than expected; reusing slicing offsets (which may be negative) as with_row_index offsets.

Related errors

• invalid `return_type`; found {return_type!r}, expected one o
• cannot use `partition_by` with `maintain_order=False, includ
• unexpected input for `strategy`: {strategy!r} Choose one of
• cannot specify both `n` and `fraction`
• can only call `.row()` without "index" or "by_predicate" val

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