pola-rs/polars · error · TypeError

invalid input for `exclude`\n\nExpected one or more `str` or

Error message

invalid input for `exclude`\n\nExpected one or more `str` or `DataType`; found {item!r} instead.

What it means

Thrown by Selector.exclude (py-polars/src/polars/selectors.py:586) when an argument passed to exclude() is neither a str (column name) nor a Polars DataType. exclude() intentionally accepts only names or dtypes; anything else — ints, None, booleans, numpy scalars — is rejected immediately with a TypeError showing the offending repr. The error occurs at selector construction time, before any DataFrame is touched.

Source

Thrown at py-polars/src/polars/selectors.py:586

        exclude_dtypes: builtins.list[PolarsDataType] = []
        for item in (
            *(
                columns
                if isinstance(columns, Collection) and not isinstance(columns, str)
                else [columns]
            ),
            *more_columns,
        ):
            if isinstance(item, str):
                exclude_cols.append(item)
            elif is_polars_dtype(item):
                exclude_dtypes.append(item)
            else:
                msg = (
                    "invalid input for `exclude`"
                    f"\n\nExpected one or more `str` or `DataType`; found {item!r} instead."
                )
                raise TypeError(msg)

        if exclude_cols and exclude_dtypes:
            msg = "cannot exclude by both column name and dtype"
            raise TypeError(msg)

        excluded = (
            by_dtype(exclude_dtypes)
            if exclude_dtypes
            else Selector._by_name(
                exclude_cols,
                strict=False,
                expand_patterns=True,
            )
        )
        return self - excluded

    def as_expr(self) -> Expr:
        """

View on GitHub (pinned to df599052da)

Solutions

Pass only column-name strings or Polars dtypes: cs.all().exclude("col_a", pl.Int64)
To exclude by position, use the index selector instead: cs.all() - cs.by_index(0) or df.select(~cs.by_index(0))
If the argument list is dynamic, sanitize it first: [x for x in items if isinstance(x, str)] and coerce pl.String/int types with pl.String, pl.Int64 before calling exclude
Check the repr in the message to find which item (and where it came from in your data/config) is invalid

Example fix

# before
df.select(cs.all().exclude(0))  # 0 is not a name or dtype

# after
df.select(cs.all().exclude("col_a", pl.Int64))
# or exclude by position:
df.select(cs.all() - cs.by_index(0))

Defensive patterns

Strategy: type-guard

Validate before calling

from polars.selectors import _expand_selector_dtypes  # not public; prefer explicit check
from polars import selectors as cs

def safe_exclude(sel, *items):
    for it in items:
        if not (isinstance(it, str) or pl.api.is_polars_dtype(it)):
            raise TypeError(f"exclude only accepts str or Polars dtype, got {it!r}")
    return sel.exclude(*items)

Type guard

from typing import TypeGuard
from polars.type_aliases import PolarsDataType

def is_exclude_arg(item: object) -> TypeGuard[str | PolarsDataType]:
    import polars as pl
    return isinstance(item, str) or pl.api.is_polars_dtype(item)

Try / catch

try:
    sel = base.exclude(*args)
except TypeError as e:
    if "invalid input for `exclude`" in str(e):
        raise ValueError(f"bad exclude args {args!r}") from e
    raise

Prevention

Type exclude() inputs in your code as str | PolarsDataType and validate at the boundary
Never pass positional indices to exclude — use cs.by_index for positions
When exclude lists come from config/JSON, validate them once at load time

When it happens

Trigger: Calling cs.all().exclude(0) (passing a column INDEX), cs.numeric().exclude(None), cs.all().exclude(True), or cs.all().exclude(["a", 1]) where the list mixes a valid name with an int. Also cs.all().exclude(pl.Int64(), 5) — the 5 fails even though the dtype is fine.

Common situations: Developers coming from a pandas/iloc mindset assume exclude takes positional indices. Others pass a computed list (e.g. from a config file or JSON) containing non-string values like 0 or None, or pass a Python type (str, int) instead of a Polars dtype (pl.String, pl.Int64).

Related errors

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