{"record":{"id":"7da9d3e67fa75f1c","repo":"pola-rs/polars","slug":"offset-must-be-an-integer-string-or-expression","errorCode":null,"errorMessage":"'offset' must be an integer, string, or expression, not {type(offset).__name__}","messagePattern":"'offset' must be an integer, string, or expression, not (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/expr/list.py","lineNumber":1132,"sourceCode":"            end of the list.\n\n        Examples\n        --------\n        >>> df = pl.DataFrame({\"a\": [[1, 2, 3, 4], [10, 2, 1]]})\n        >>> df.with_columns(slice=pl.col(\"a\").list.slice(1, 2))\n        shape: (2, 2)\n        ┌─────────────┬───────────┐\n        │ a           ┆ slice     │\n        │ ---         ┆ ---       │\n        │ list[i64]   ┆ list[i64] │\n        ╞═════════════╪═══════════╡\n        │ [1, 2, … 4] ┆ [2, 3]    │\n        │ [10, 2, 1]  ┆ [2, 1]    │\n        └─────────────┴───────────┘\n        \"\"\"\n        if isinstance(offset, Collection) and not isinstance(offset, str):\n            msg = f\"'offset' must be an integer, string, or expression, not {type(offset).__name__}\"\n            raise TypeError(msg)\n        if (\n            length is not None\n            and isinstance(length, Collection)\n            and not isinstance(length, str)\n        ):\n            msg = f\"'length' must be an integer, string, or expression, not {type(length).__name__}\"\n            raise TypeError(msg)\n\n        offset_pyexpr = parse_into_expression(offset)\n        length_pyexpr = parse_into_expression(length)\n        return wrap_expr(self._pyexpr.list_slice(offset_pyexpr, length_pyexpr))\n\n    def head(self, n: int | str | Expr = 5) -> Expr:\n        \"\"\"\n        Slice the first `n` values of every sub-list.\n\n        .. engine-support:: in-memory, streaming, distributed\n","sourceCodeStart":1114,"sourceCodeEnd":1150,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/expr/list.py#L1114-L1150","documentation":"Expr.list.slice validates `offset` before parsing it into an expression: it must be an int, a column name (str), or an Expr — anything that is a collections.abc.Collection (except str), such as a list, tuple, set, or dict, raises TypeError with the offending type name. The rejection exists because a bare collection is almost always a mistake (e.g. passing a list of per-row offsets that was never wrapped as a Series/Expr) and parse_into_expression would otherwise misinterpret it.","triggerScenarios":"pl.col('l').list.slice([1, 2]) or list.slice(offset=(1,)) — passing a Python list/tuple where an int or expression is expected; also np arrays if registered as collections.","commonSituations":"Wanting per-row offsets: developers have a Python list of offsets (one per row) and pass it directly instead of a column; API wrappers that accept Sequence[int] and forward it unchanged; confusing slice semantics with Python's list slicing that accepts tuples.","solutions":["For a constant offset pass an int: list.slice(1).","For per-row offsets, put them in a column and pass an expression: list.slice(pl.col('offs')) or the column name as str.","In generic wrappers, convert Sequences with pl.Series(offset) inside pl.lit(...) or select-based expressions before forwarding."],"exampleFix":"# before\npl.col('l').list.slice(offset=[1, 2])\n\n# after\npl.col('l').list.slice(offset=1)\n# per-row offsets:\ndf.with_columns(pl.col('l').list.slice(pl.col('offs')))","handlingStrategy":"type-guard","validationCode":"from collections.abc import Collection\nif isinstance(offset, Collection) and not isinstance(offset, str):\n    raise TypeError(f'offset must be int/str/Expr, got {type(offset).__name__}')","typeGuard":"from collections.abc import Collection\n\ndef is_valid_slice_arg(v) -> bool:\n    return v is None or isinstance(v, (int, str)) or hasattr(v, '_pyexpr')","tryCatchPattern":null,"preventionTips":["list.slice takes int | str | Expr — wrap Python sequences in a column first.","Never forward untyped Sequence parameters from public APIs into polars expression arguments."],"tags":["type-guard","polars","expression","list","slice"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}