pola-rs/polars · error · TypeError

DataFrame constructor called with unsupported type {type(dat

Error message

DataFrame constructor called with unsupported type {type(data).__name__!r} for the `data` parameter

What it means

The terminal TypeError of the polars DataFrame constructor: `data` did not match any supported branch (dict, sequence, numpy array, Arrow, pandas, pathlib/None for empty, pycapsule). Polars dispatches by exact type at the top of __init__, and an unrecognized type falls through to this error naming the offending type.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:490

            )

        elif isinstance(data, pl.DataFrame):
            self._df = dataframe_to_pydf(
                data, schema=schema, schema_overrides=schema_overrides, strict=strict
            )

        elif is_pycapsule(data):
            self._df = pycapsule_to_frame(
                data,
                schema=schema,
                schema_overrides=schema_overrides,
            )._df
        else:
            msg = (
                f"DataFrame constructor called with unsupported type {type(data).__name__!r}"
                " for the `data` parameter"
            )
            raise TypeError(msg)

        if height is not None and self.height != height:
            from polars.exceptions import ShapeError

            msg = f"height of data ({self.height}) does not match specified height ({height})"
            raise ShapeError(msg)

    @classmethod
    def deserialize(
        cls,
        source: str | bytes | Path | IOBase,
        *,
        format: SerializationFormat = "binary",
    ) -> DataFrame:
        """
        Read a serialized DataFrame from a file.

        Parameters

View on GitHub (pinned to df599052da)

Solutions

Wrap scalars/iterables: pl.DataFrame({'col': [value]}) or pl.DataFrame(list(data))
Convert sets to lists: pl.DataFrame(sorted(s))
For pandas/Arrow origins use pl.from_pandas / pl.from_arrow
For dataclasses use pl.DataFrame([asdict(o) for o in objects])
For generators, materialize first: pl.DataFrame(list(gen))

Example fix

# before
df = pl.DataFrame(set([1, 2, 3]))

# after
df = pl.DataFrame({'value': sorted({1, 2, 3})})

Defensive patterns

Strategy: type-guard

Validate before calling

import polars as pl

def frame_from_any(data):
    match data:
        case pl.DataFrame() | pl.Series():
            return data if isinstance(data, pl.DataFrame) else data.to_frame()
        case dict():
            return pl.DataFrame(data)
        case list() | tuple():
            return pl.DataFrame(data)
        case _:
            return pl.DataFrame([data])  # last resort: single-row frame

Type guard

import polars as pl
from typing import TypeGuard

def is_frame_constructible(data: object) -> TypeGuard[dict | list | tuple | pl.Series]:
    return isinstance(data, (dict, list, tuple, pl.Series))

Try / catch

try:
    df = pl.DataFrame(data)
except TypeError as e:
    raise TypeError(
        f'cannot build DataFrame from {type(data).__name__}; '
        'convert to list/dict first or use from_pandas/from_arrow'
    ) from e

Prevention

Convert sets to lists and materialize generators before construction
Route pandas/Arrow objects through their dedicated from_* converters
Keep constructor inputs to dict-of-columns or list-of-rows shapes in shared code

When it happens

Trigger: pl.DataFrame(5), pl.DataFrame('text'), pl.DataFrame(set([1,2,3])), pl.DataFrame(lambda x: x), pl.DataFrame(some_custom_class), or passing a pyarrow-compatible object that does not implement the pycapsule/Arrow interfaces. Also passing a single pl.Series not wrapped in a list (depending on shape) can land here.

Common situations: Porting pandas muscle memory (pd.DataFrame(scalar) works, pl does not); passing sets (e.g. from a group_by result); feeding ORM cursors, generators, or dataclasses; third-party DataFrame-like objects without Arrow support.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/c18d22391a2d3e24. Report an issue: GitHub.