pola-rs/polars · error · TypeError

Enum categories must not contain null values

Error message

Enum categories must not contain null values

What it means

Enum categories in Polars form the fixed set of allowed string values, so they must not contain nulls. A Series of candidate categories containing any null value is rejected with this TypeError at construction time.

Solutions

1. Drop nulls first: pl.Enum(series.drop_nulls())
2. Use .unique().drop_nulls() when deriving categories from a column
3. Filter None values from the Python list before constructing the Series

Example fix

// before
pl.Enum(df['status'].unique())
// after
pl.Enum(df['status'].unique().drop_nulls())

series = pl.Series(values)
if series.has_nulls():
    series = series.drop_nulls()
categories = pl.Enum(series)

def is_null_free_string_series(s: pl.Series) -> bool:
    return s.dtype == pl.String and not s.has_nulls()

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

When it happens

Trigger: pl.Series(["a", None, "b"]) passed to pl.Enum(...); building categories from a nullable column via .unique() without dropping nulls; enum classes whose values include None.

Common situations: Deriving categories from raw data columns that contain missing values; upstream data with nulls flowing into dtype definitions.

Related errors

• Enum categories must be unique; found duplicate
• at least one of ('key', 'max_rows_per_file'…
• can not get dtype of Enum AnyValue
• can't order enums from different FrozenCategories
• cannot use 'include_key' without specifying 'key'

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

Appendix: source

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

                if issubclass(categories, enum_subclass):
                    enum_type_name = categories.__name__
                    msg = f"Enum categories must be strings; `{enum_type_name}` values are integers"
                    raise TypeError(msg)

            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)

View on GitHub (pinned to fe841f959e)