pola-rs/polars · error · TypeError

DataTypeGroup items must be dtypes; found

Error message

DataTypeGroup items must be dtypes; found {qualified_type_name(it)!r}

What it means

polars DataTypeGroup (used for set-like dtype collections) validates that every item is a DataType instance or DataTypeClass. __new__ raises TypeError for any element that is not a dtype, e.g. raw strings like 'Int64' or None.

Solutions

1. Replace string dtype names with polars DataType objects, e.g. 'Int64' -> pl.Int64
2. Wrap strings with pl.DataType if constructing from config: getattr(pl, name)
3. Filter/validate the list before constructing the group, dropping or converting non-dtype items
4. Check for None or nested lists that leaked into the items iterable

Example fix

// before
pl.datatypes.group.DataTypeGroup(['Int64', 'Utf8'])
// after
pl.datatypes.group.DataTypeGroup([pl.Int64, pl.Utf8])

def check_dtypes(items):
    import polars as pl
    bad = [it for it in items if not isinstance(it, (pl.DataType, type(pl.Int64)))]
    if bad:
        raise TypeError(f'non-dtype items: {bad}')

from polars import DataType
def is_dtype(x) -> bool:
    return isinstance(x, (DataType, type(DataType)))

When it happens

Trigger: Calling DataTypeGroup([...]) or passing a collection to a dtype-group parameter where a list element is a plain string, None, a Python type alias, or any non-dtype object.

Common situations: Migrating from string dtype names to polars DataType objects; typos like passing 'Int64' instead of pl.Int64; accidentally passing a numpy dtype or built-in type; building groups programmatically from config values that are strings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• arr.to_struct() got a str instead of a list. hint: pass
• cannot call `map_groups` when filtering groups with `having`
• cannot call `map_groups` when grouping by an expression
• cannot call `map_groups` when grouping by named expressions
• cannot set Series of dtype

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

Appendix: source

Thrown at py-polars/src/polars/datatypes/group.py:71

    def __new__(
        cls, items: Iterable[DataType | DataTypeClass], *, match_base_type: bool = True
    ) -> Self:
        """
        Construct a DataTypeGroup.

        Parameters
        ----------
        items :
            iterable of data types
        match_base_type:
            match the base type
        """
        for it in items:
            if not isinstance(it, (DataType, DataTypeClass)):
                from polars._utils.various import qualified_type_name

                msg = f"DataTypeGroup items must be dtypes; found {qualified_type_name(it)!r}"
                raise TypeError(msg)

        dtype_group = super().__new__(cls, items)
        dtype_group._match_base_type = match_base_type
        return dtype_group

    def __contains__(self, item: Any) -> bool:
        if self._match_base_type and isinstance(item, (DataType, DataTypeClass)):
            item = item.base_type()
        return super().__contains__(item)


SIGNED_INTEGER_DTYPES: Final[frozenset[PolarsIntegerType]] = DataTypeGroup(
    [
        Int8,
        Int16,
        Int32,
        Int64,
        Int128,

View on GitHub (pinned to fe841f959e)