pola-rs/polars · error · TypeError

cannot select columns using Series of type {dtype}

Error message

cannot select columns using Series of type {dtype}

What it means

When a pl.Series is used as a DataFrame indexing key, polars selects columns by String dtype (names), integer dtypes (positions), or Boolean dtype (mask). Any other Series dtype — Float64, Categorical, temporal — is ambiguous and raises TypeError with the dtype name.

Source

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

        elif isinstance(first, str):
            return _select_columns_by_name(df, key)  # type: ignore[arg-type]
        else:
            msg = f"cannot select columns using Sequence with elements of type {qualified_type_name(first)!r}"
            raise TypeError(msg)

    elif isinstance(key, pl.Series):
        if key.is_empty():
            return df.__class__()
        dtype = key.dtype
        if dtype == String:
            return _select_columns_by_name(df, key)
        elif dtype.is_integer():
            return _select_columns_by_index(df, key)
        elif dtype == Boolean:
            return _select_columns_by_mask(df, key)
        else:
            msg = f"cannot select columns using Series of type {dtype}"
            raise TypeError(msg)

    elif _check_for_numpy(key) and isinstance(key, np.ndarray):
        if key.ndim == 0:
            key = np.atleast_1d(key)
        elif key.ndim != 1:
            msg = "multi-dimensional NumPy arrays not supported as index"
            raise TypeError(msg)

        if len(key) == 0:
            return df.__class__()

        dtype_kind = key.dtype.kind
        if dtype_kind in ("i", "u"):
            return _select_columns_by_index(df, key)
        elif dtype_kind == "b":
            return _select_columns_by_mask(df, key)
        elif isinstance(key[0], str):
            return _select_columns_by_name(df, key)

View on GitHub (pinned to df599052da)

Solutions

1. Cast positions: df[key.cast(pl.Int64)].
2. Select by name: df[key.cast(pl.String)] or df.select(key_str).
3. Generate integer ranges correctly: pl.int_range(...) or np.arange(..., dtype=int).

Example fix

// before
idx = pl.Series(np.arange(4) / 2)  # Float64
cols = df[idx]

// after
cols = df[idx.cast(pl.Int64))

key = pl.Series(key) if not isinstance(key, pl.Series) else key
if key.dtype == pl.String or key.dtype.is_integer() or key.dtype == pl.Boolean:
    out = df[key]
else:
    if key.dtype.is_float() and key.cast(pl.Int64).cast(pl.Float64).equals(key):
        out = df[key.cast(pl.Int64)]
    else:
        raise TypeError(f"Series key dtype {key.dtype} cannot select columns")

def is_column_select_series(key: pl.Series) -> bool:
    return key.dtype == pl.String or key.dtype.is_integer() or key.dtype == pl.Boolean

try:
    out = df[key]
except TypeError as e:
    if "cannot select columns using Series of type" in str(e):
        out = df[key.cast(pl.Int64)] if key.dtype.is_float() else df[key.cast(pl.String)]
    else:
        raise

When it happens

Trigger: df[pl.Series([0.5, 1.5])]; df[key] where key came from float arithmetic (np.arange(n) / step); df[some_float_column].

Common situations: Column indices computed as float ratios (e.g. np.linspace over positions); reusing a data column as a selection key without checking its dtype; indices converted through float stages in a pipeline.

Related errors

• cannot select columns using NumPy array of type {key.dtype}
• can't convert {pyseries.dtype()} to Decimal
• cannot initialize Series from DataFrame without any columns
• cannot select columns using Sequence with elements of type {
• cannot select columns using key of type {qualified_type_name

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/f9eb0a68a93b71c3. Report an issue: GitHub.