pola-rs/polars · error · DuplicateError

iterable passed to pl.Schema contained duplicate name

Error message

iterable passed to pl.Schema contained duplicate name '{name}'

What it means

Duplicate-name check in pl.Schema.__init__: while ingesting an iterable/Mapping of (name, dtype) pairs, a field name appears more than once, which is illegal because a schema is a name-keyed mapping; construction raises.

Solutions

Deduplicate the (name, dtype) pairs before constructing the Schema
De-duplicate the source names list, keeping the desired occurrence
Use a dict literal, which enforces unique keys at write time

Example fix

// before
pl.Schema(zip(names, dtypes))  # names contains 'a' twice
// after
pl.Schema(dict(zip(names, dtypes)))  # or dedupe names first

Defensive patterns

Strategy: validation

Validate before calling

seen = set()
pairs = [(n, t) for n, t in pairs if not (n in seen or seen.add(n))]
schema = pl.Schema(pairs)

Try / catch

try:
    schema = pl.Schema(pairs)
except pl.exceptions.DuplicateError as e:
    schema = pl.Schema(dict(pairs))  # last-wins dedupe

Prevention

Deduplicate name/dtype pairs before building a Schema
Prefer dict literals, which enforce unique keys
Validate upstream sources (joins, concatenations) for duplicate names

When it happens

Trigger: pl.Schema([("a", pl.Int64), ("a", pl.Utf8)]) — an iterable (generator/list of tuples) containing the same name twice.

Common situations: Programmatically zipping a names list with a dtypes list where names repeat; concatenating pairs from multiple sources.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at py-polars/src/polars/schema.py:145

    ) -> None:
        if _is_arrow_schema_exportable(schema) and not isinstance(schema, Schema):
            init_polars_schema_from_arrow_c_schema(self, schema)
            return

        # `Mapping[tuple[str, SchemaInitDataType]]` is not valid at runtime, even
        # though it is a `Iterable[tuple[str, SchemaInitDataType]]`.
        input: Iterable[tuple[str, SchemaInitDataType] | ArrowSchemaExportable]
        input = schema.items() if isinstance(schema, Mapping) else (schema or ())  # type: ignore[assignment]
        for v in input:
            name, tp = (
                polars_schema_field_from_arrow_c_schema(v)
                if _is_arrow_schema_exportable(v)
                else v
            )

            if name in self:
                msg = f"iterable passed to pl.Schema contained duplicate name '{name}'"
                raise DuplicateError(msg)

            if not check_dtypes:
                super().__setitem__(name, tp)  # type: ignore[assignment]
            elif is_polars_dtype(tp):
                super().__setitem__(name, _check_dtype(tp))
            else:
                self[name] = tp

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Mapping):
            return False
        if len(self) != len(other):
            return False
        for (nm1, tp1), (nm2, tp2) in zip(self.items(), other.items(), strict=True):
            if nm1 != nm2 or not tp1.is_(tp2):
                return False
        return True

View on GitHub (pinned to fe841f959e)