{"record":{"id":"dc5ab597bf25fba8","repo":"pola-rs/polars","slug":"index-positions-should-be-greater-than-or-equal-to","errorCode":null,"errorMessage":"index positions should be greater than or equal to -2^32","messagePattern":"index positions should be greater than or equal to -2\\^32","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/getitem.py","lineNumber":374,"sourceCode":"        return s\n\n    if not s.dtype.is_integer():\n        if s.dtype == Boolean:\n            _raise_on_boolean_mask()\n        else:\n            msg = f\"cannot treat Series of type {s.dtype} as indices\"\n            raise TypeError(msg)\n\n    if s.len() == 0:\n        return pl.Series(s.name, [], dtype=idx_type)\n\n    if idx_type == UInt32:\n        if s.dtype in {Int64, UInt64} and s.max() >= U32_MAX:  # type: ignore[operator]\n            msg = \"index positions should be smaller than 2^32\"\n            raise ValueError(msg)\n        if s.dtype == Int64 and s.min() < -U32_MAX:  # type: ignore[operator]\n            msg = \"index positions should be greater than or equal to -2^32\"\n            raise ValueError(msg)\n\n    if s.dtype.is_signed_integer():\n        if s.min() < 0:  # type: ignore[operator]\n            if idx_type == UInt32:\n                idxs = s.cast(Int32) if s.dtype in {Int8, Int16} else s\n            else:\n                idxs = s.cast(Int64) if s.dtype in {Int8, Int16, Int32} else s\n\n            # Update negative indexes to absolute indexes.\n            return (\n                idxs.to_frame()\n                .select(\n                    F.when(F.col(idxs.name) < 0)\n                    .then(size + F.col(idxs.name))\n                    .otherwise(F.col(idxs.name))\n                    .cast(idx_type)\n                )\n                .to_series(0)","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/getitem.py#L356-L392","documentation":"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.","triggerScenarios":"df[pl.Series([-(2**32) - 1], dtype=pl.Int64)]; sentinel values like -9999999999 in an index column; arithmetic that produces very large negative offsets.","commonSituations":"Sentinel/fill values (-1 padded to 64-bit extremes) leaking into index Series; bugs computing relative offsets far outside the frame height.","solutions":["Fix the negative values: valid row positions must satisfy -df.height <= i < df.height","Drop or clamp sentinels before indexing: idx = idx.filter(idx >= -df.height)","Install polars-u64-idx if the large negative values are legitimate in your pipeline"],"exampleFix":"# before\ndf[pl.Series([-5_000_000_000], dtype=pl.Int64)]\n\n# after\ndf[pl.Series([-1], dtype=pl.Int64)]  # valid negative offset within height","handlingStrategy":"validation","validationCode":"if idx.dtype == pl.Int64 and idx.len() and idx.min() < -(2**32):\n    raise ValueError(\"negative positions below -2^32 are invalid\")\ndf[idx]","typeGuard":"def above_neg_u32_floor(s: \"pl.Series\") -> bool:\n    return not (s.dtype == pl.Int64 and s.len() and (s.min() if s.min() is not None else 0) < -(2**32))","tryCatchPattern":null,"preventionTips":["Valid negative positions are within [-df.height, -1]; anything lower is a bug","Filter sentinel values out of index Series before indexing","Prefer absolute positions when indices come from external systems"],"tags":["python","polars","indices","uint32","limits","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}