{"record":{"id":"5308d076d2b9e087","repo":"pola-rs/polars","slug":"offset-input-for-with-row-index-cannot-be-iss-5308d0","errorCode":null,"errorMessage":"`offset` input for `with_row_index` cannot be {issue}, got {offset}","messagePattern":"`offset` input for `with_row_index` cannot be (.+?), got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":7510,"sourceCode":"        ...     pl.all(),\n        ... ).collect()\n        shape: (3, 3)\n        ┌───────┬─────┬─────┐\n        │ index ┆ a   ┆ b   │\n        │ ---   ┆ --- ┆ --- │\n        │ u32   ┆ i64 ┆ i64 │\n        ╞═══════╪═════╪═════╡\n        │ 0     ┆ 1   ┆ 2   │\n        │ 1     ┆ 3   ┆ 4   │\n        │ 2     ┆ 5   ┆ 6   │\n        └───────┴─────┴─────┘\n        \"\"\"\n        try:\n            return self._from_pyldf(self._ldf.with_row_index(name, offset))\n        except OverflowError:\n            issue = \"negative\" if offset < 0 else \"greater than the maximum index value\"\n            msg = f\"`offset` input for `with_row_index` cannot be {issue}, got {offset}\"\n            raise ValueError(msg) from None\n\n    @deprecated(\n        \"`LazyFrame.with_row_count` is deprecated; use `LazyFrame.with_row_index` instead.\"\n        \" Note that the default column name has changed from 'row_nr' to 'index'.\"\n    )\n    def with_row_count(self, name: str = \"row_nr\", offset: int = 0) -> LazyFrame:\n        \"\"\"\n        Add a column at index 0 that counts the rows.\n\n        .. deprecated:: 0.20.4\n            Use the :meth:`with_row_index` method instead.\n            Note that the default column name has changed from 'row_nr' to 'index'.\n\n        Parameters\n        ----------\n        name\n            Name of the column to add.\n        offset","sourceCodeStart":7492,"sourceCodeEnd":7528,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/frame.py#L7492-L7528","documentation":"LazyFrame.with_row_index(name, offset) propagates an OverflowError from the Rust engine as ValueError when offset is negative or exceeds the maximum index value (unsigned integer bound). The offset seeds the row counter, so it must be a non-negative in-range integer.","triggerScenarios":"lf.with_row_index(offset=-1); offsets computed from prior chunk sizes or batch counters that underflow; offsets loaded from config/file parsed as negative; very large offsets beyond u32/u64 bounds after multiprocessing sharding math.","commonSituations":"Sharded/batched processing where each shard offsets by cumulative row counts (off-by-one or empty-shard math producing -1); user-supplied start indices; migrating from with_row_count which had different validation.","solutions":["Clamp: offset = max(0, offset) if a non-negative counter is acceptable","Fix the shard math: use running_total sums of previous shard heights, never differences that can underflow","Validate offset is an int in [0, 2**32) before calling when using default u32 index dtype","Consider chaining an explicit offset column via with_columns if arbitrary integers are needed"],"exampleFix":"# before\nstart = prev_rows - batch  # can be -1 on first batch\nlf.with_row_index(offset=start)\n\n# after\nstart = max(0, prev_rows - batch)\nlf.with_row_index(offset=start)","handlingStrategy":"validation","validationCode":"offset = int(offset)\nif offset < 0:\n    raise ValueError(f'row index offset must be >= 0, got {offset}')\nlf = lf.with_row_index(name, offset)","typeGuard":"def is_valid_row_index_offset(offset) -> bool:\n    return isinstance(offset, int) and 0 <= offset < 2**32","tryCatchPattern":"try:\n    lf.with_row_index(offset=offset)\nexcept ValueError:\n    lf.with_row_index(offset=max(0, offset))  # or recompute shard offset","preventionTips":["Compute shard offsets as cumulative sums, never differences","Validate offset range at batch-job start","Unit test batch math with empty first batches"],"tags":["polars","lazyframe","with-row-index","overflow","negative-value"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}