{"record":{"id":"c18d22391a2d3e24","repo":"pola-rs/polars","slug":"dataframe-constructor-called-with-unsupported-type","errorCode":null,"errorMessage":"DataFrame constructor called with unsupported type {type(data).__name__!r} for the `data` parameter","messagePattern":"DataFrame constructor called with unsupported type (.+?) for the `data` parameter","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":490,"sourceCode":"            )\n\n        elif isinstance(data, pl.DataFrame):\n            self._df = dataframe_to_pydf(\n                data, schema=schema, schema_overrides=schema_overrides, strict=strict\n            )\n\n        elif is_pycapsule(data):\n            self._df = pycapsule_to_frame(\n                data,\n                schema=schema,\n                schema_overrides=schema_overrides,\n            )._df\n        else:\n            msg = (\n                f\"DataFrame constructor called with unsupported type {type(data).__name__!r}\"\n                \" for the `data` parameter\"\n            )\n            raise TypeError(msg)\n\n        if height is not None and self.height != height:\n            from polars.exceptions import ShapeError\n\n            msg = f\"height of data ({self.height}) does not match specified height ({height})\"\n            raise ShapeError(msg)\n\n    @classmethod\n    def deserialize(\n        cls,\n        source: str | bytes | Path | IOBase,\n        *,\n        format: SerializationFormat = \"binary\",\n    ) -> DataFrame:\n        \"\"\"\n        Read a serialized DataFrame from a file.\n\n        Parameters","sourceCodeStart":472,"sourceCodeEnd":508,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L472-L508","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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))"],"exampleFix":"# before\ndf = pl.DataFrame(set([1, 2, 3]))\n\n# after\ndf = pl.DataFrame({'value': sorted({1, 2, 3})})","handlingStrategy":"type-guard","validationCode":"import polars as pl\n\ndef frame_from_any(data):\n    match data:\n        case pl.DataFrame() | pl.Series():\n            return data if isinstance(data, pl.DataFrame) else data.to_frame()\n        case dict():\n            return pl.DataFrame(data)\n        case list() | tuple():\n            return pl.DataFrame(data)\n        case _:\n            return pl.DataFrame([data])  # last resort: single-row frame","typeGuard":"import polars as pl\nfrom typing import TypeGuard\n\ndef is_frame_constructible(data: object) -> TypeGuard[dict | list | tuple | pl.Series]:\n    return isinstance(data, (dict, list, tuple, pl.Series))","tryCatchPattern":"try:\n    df = pl.DataFrame(data)\nexcept TypeError as e:\n    raise TypeError(\n        f'cannot build DataFrame from {type(data).__name__}; '\n        'convert to list/dict first or use from_pandas/from_arrow'\n    ) from e","preventionTips":["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"],"tags":["dataframe-constructor","type-mismatch","pandas-migration"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}