{"record":{"id":"5308d076d2b9e087","repo":"pola-rs/polars","slug":"offset-input-for-with-row-index-cannot-be-iss","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":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":7238,"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    def gather_every(self, n: int, offset: int = 0) -> LazyFrame:\n        \"\"\"\n        Take every nth row in the LazyFrame and return as a new LazyFrame.\n\n        .. engine-support:: in-memory, streaming\n\n        Parameters\n        ----------\n        n\n            Gather every *n*-th row.\n        offset\n            Starting index.\n\n        Examples\n        --------\n        >>> lf = pl.LazyFrame(\n        ...     {","sourceCodeStart":7220,"sourceCodeEnd":7256,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L7220-L7256","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure offset >= 0 and within the supported index range (check it against 2**32 - 1 or the documented maximum)","Clamp or validate the offset before the call","Use int(x) on numpy/pandas scalars to avoid odd overflow conversions"],"exampleFix":"// before\nlf.with_row_index('idx', offset=-10)\n// after\noffset = max(0, computed_offset)\nlf.with_row_index('idx', offset=offset)","handlingStrategy":"validation","validationCode":"MAX_OFFSET = 2**32 - 1\ndef safe_with_row_index(lf, name, offset):\n    if offset is None:\n        return lf.with_row_index(name)\n    if not (0 <= offset <= MAX_OFFSET):\n        raise ValueError(f'offset must be 0..{MAX_OFFSET}, got {offset}')\n    return lf.with_row_index(name, offset)","typeGuard":"def offset_ok(offset) -> bool:\n    return isinstance(offset, int) and 0 <= offset <= 2**32 - 1","tryCatchPattern":"try:\n    out = lf.with_row_index('idx', offset)\nexcept ValueError as e:\n    if '`offset` input for `with_row_index`' in str(e):\n        offset = max(0, offset)\n        out = lf.with_row_index('idx', offset)\n    else:\n        raise","preventionTips":["Validate offsets are non-negative and fit in the engine's index type","Convert numpy integers with int() before passing","Never reuse slice-style negative offsets for row indices"],"tags":["polars","python","row-index","overflow","argument-validation"],"backgroundTag":"value-out-of-range","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}