pola-rs/polars · error · ValueError

Enum categories must be unique; found duplicate

Error message

Enum categories must be unique; found duplicate {duplicate!r}

What it means

Validation when constructing an Enum dtype: after converting categories to a Series, uniqueness is checked via n_unique vs len; a duplicated category would make the enum's category mapping ambiguous, so construction raises. Provide a list/Series of distinct non-null strings.

Solutions

Call .unique() on the Series before passing it: pl.Enum(categories.unique())
Use sorted(set(values)) for plain iterables
Deduplicate enum aliases or pass the alias-free values explicitly

Example fix

// before
pl.Enum(pl.Series(['a', 'b', 'a']))
// after
pl.Enum(pl.Series(['a', 'b', 'a']).unique())

Defensive patterns

Strategy: validation

Validate before calling

series = pl.Series(values) if not isinstance(values, pl.Series) else values
if series.n_unique() != series.len():
    series = series.unique()
categories = pl.Enum(series)

Type guard

def has_unique_categories(s: pl.Series) -> bool:
    return s.n_unique() == s.len()

Try / catch

try:
    dtype = pl.Enum(categories)
except ValueError:
    dtype = pl.Enum(categories.unique())

Prevention

Deduplicate inputs with .unique() or set() before constructing
Watch for Python enum aliases creating duplicate values
Assert uniqueness in unit tests for shared category definitions

When it happens

Trigger: pl.Enum(pl.Series(['a', 'b', 'a'])); deriving categories with duplicates from raw data without .unique(); string enum classes with two members sharing the same value.

Common situations: Hand-assembled category lists from merged sources; Python enums with aliases (two names, one value) flattened to duplicates.

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

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

Appendix: source

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

        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:
        return hash((self.__class__, tuple(self.categories)))

    def __repr__(self) -> str:
        class_name = self.__class__.__name__
        return f"{class_name}(categories={self.categories.to_list()!r})"

View on GitHub (pinned to fe841f959e)