pola-rs/polars · error · TypeError

Enum categories must be strings; found data of type

Error message

Enum categories must be strings; found data of type {dtype}

What it means

Enum categories must be a Series of pl.String (or convertible iterable of str). If the provided Series has any other dtype (e.g. Int64, Categorical, Date), a TypeError naming the found dtype is raised.

Solutions

1. Cast the Series to String: pl.Enum(categories.cast(pl.String))
2. Pass a list of Python strings or a String-typed Series
3. Convert numeric values to strings explicitly before constructing

Example fix

// before
pl.Enum(pl.Series([1, 2, 3]))
// after
pl.Enum(pl.Series(['1', '2', '3']))

series = values if isinstance(values, pl.Series) else pl.Series(values)
if series.dtype != pl.String:
    series = series.cast(pl.String)
categories = pl.Enum(series)

def is_string_series(s: pl.Series) -> bool:
    return isinstance(s, pl.Series) and s.dtype == pl.String

try:
    dtype = pl.Enum(categories)
except TypeError:
    dtype = pl.Enum(categories.cast(pl.String))

When it happens

Trigger: pl.Enum(pl.Series([1, 2, 3])) (integer values); passing a numeric column's unique values as categories; pl.Enum of a Series of datetimes.

Common situations: Reusing numeric code columns as enum categories; forgetting that Python ints produce Int64 Series; deriving categories from non-string columns.

Related errors

• Enum categories must be strings;
• cannot parse input into Polars selector
• dtype ' ' is a BaseExtension class, it should be an instance
• invalid dtype for `ones`; found
• invalid dtype for `zeros`; found

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

Appendix: source

Thrown at py-polars/src/polars/datatypes/classes.py:1033

            enum_values = [
                getattr(v, "value", v) for v in categories.__members__.values()
            ]
            categories = pl.Series(values=enum_values)
        elif not isinstance(categories, pl.Series):
            categories = pl.Series(values=categories)

        if categories.is_empty():
            self.categories = pl.Series(name="category", dtype=String)
            return

        if categories.has_nulls():
            msg = "Enum categories must not contain null values"
            raise TypeError(msg)

        if (dtype := categories.dtype) != String:
            msg = f"Enum categories must be strings; found data of type {dtype}"
            raise TypeError(msg)

        if categories.n_unique() != categories.len():
            duplicate = categories.filter(categories.is_duplicated())[0]
            msg = f"Enum categories must be unique; found duplicate {duplicate!r}"
            raise ValueError(msg)

        self.categories = categories.rechunk().alias("category")

    def __eq__(self, other: PolarsDataType) -> bool:  # type: ignore[override]
        # allow comparing object instances to class
        if type(other) is DataTypeClass and issubclass(other, Enum):
            return True
        elif isinstance(other, Enum):
            return self.categories.equals(other.categories)
        else:
            return False

    def __hash__(self) -> int:

View on GitHub (pinned to fe841f959e)