pola-rs/polars · error · TypeError

selecting rows by passing a boolean mask to `getitem`…

Error message

selecting rows by passing a boolean mask to `__getitem__` is not supported

Hint: Use the `filter` method instead.

What it means

Polars deliberately removed support for boolean-mask row selection through `__getitem__`. `_raise_on_boolean_mask` raises a TypeError directing users to the `filter` method, which is the supported (and faster/lazier-optimizable) API for mask-based row selection.

Solutions

Use `df.filter(pl.col('a') > 5)` for DataFrames.
Use `s.filter(mask)` for Series.
For NumPy bool arrays, convert: `s.filter(pl.Series(mask))`.

Example fix

// before
out = df[df['a'] > 5]  # TypeError
// after
out = df.filter(pl.col('a') > 5)

Defensive patterns

Strategy: fallback

Validate before calling

if isinstance(mask, (pl.Series, np.ndarray)) and mask.dtype in (pl.Boolean, bool, np.bool_):
    return s.filter(pl.Series(mask))

Type guard

def is_boolean_mask(x) -> bool:
    return (isinstance(x, pl.Series) and x.dtype == pl.Boolean) or (isinstance(x, np.ndarray) and x.dtype == np.bool_)

Try / catch

try:
    out = df[mask]
except TypeError as e:
    if "boolean mask" in str(e):
        out = df.filter(pl.Series(mask))
    else:
        raise

Prevention

Replace pandas-style `df[mask]` with `df.filter(cond)` when porting code.
Grep codebases for `df[df.` patterns during pandas->polars migration.
Use `pl.col(...) > x` expressions directly inside `.filter()`.

When it happens

Trigger: `s[mask]` or `df[mask]` where mask is a boolean Series or NumPy bool array, e.g. `df[df['a'] > 5]`, `s[pl.Series([True, False, True])]`.

Common situations: Pandas-style habits: `df[df.x > 0]` works in pandas but not polars `__getitem__`; migrating pandas notebooks; quick REPL filtering.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/531a5c8280fdc5b3. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/_utils/getitem.py:457

        else:
            if arr.dtype in (np.int8, np.int16, np.int32):
                arr = arr.astype(np.int64)

        # Update negative indexes to absolute indexes.
        arr = np.where(arr < 0, size + arr, arr)

    # numpy conversion is much faster
    arr = arr.astype(np.uint32) if idx_type == UInt32 else arr.astype(np.uint64)

    return pl.Series("", arr, dtype=idx_type)


def _raise_on_boolean_mask() -> NoReturn:
    msg = (
        "selecting rows by passing a boolean mask to `__getitem__` is not supported"
        "\n\nHint: Use the `filter` method instead."
    )
    raise TypeError(msg)

View on GitHub (pinned to fe841f959e)

selecting rows by passing a boolean mask to `__getitem__`…