{"record":{"id":"8d0a9f79d3a7f329","repo":"pola-rs/polars","slug":"cannot-construct-pyseries-for-type-dtype-r","errorCode":null,"errorMessage":"cannot construct PySeries for type {dtype!r}","messagePattern":"cannot construct PySeries for type (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/constructor.py","lineNumber":75,"sourceCode":"        bytes: PySeries.new_binary,\n        PyDecimal: PySeries.new_decimal,\n    }\n\n\ndef polars_type_to_constructor(\n    dtype: PolarsDataType,\n) -> Callable[[str, Sequence[Any], bool], PySeries]:\n    \"\"\"Get the right PySeries constructor for the given Polars dtype.\"\"\"\n    # Special case for Array as it needs to pass the dtype argument on construction\n    if isinstance(dtype, dt.Array):\n        return functools.partial(PySeries.new_array, dtype=dtype)\n\n    try:\n        base_type = dtype.base_type()\n        return _POLARS_TYPE_TO_CONSTRUCTOR[base_type]\n    except KeyError:  # pragma: no cover\n        msg = f\"cannot construct PySeries for type {dtype!r}\"\n        raise ValueError(msg) from None\n\n\n_NUMPY_TYPE_TO_CONSTRUCTOR = None\n\n\ndef _set_numpy_to_constructor() -> None:\n    global _NUMPY_TYPE_TO_CONSTRUCTOR\n    _NUMPY_TYPE_TO_CONSTRUCTOR = {\n        np.float16: PySeries.new_f16,\n        np.float32: PySeries.new_f32,\n        np.float64: PySeries.new_f64,\n        np.int8: PySeries.new_i8,\n        np.int16: PySeries.new_i16,\n        np.int32: PySeries.new_i32,\n        np.int64: PySeries.new_i64,\n        np.uint8: PySeries.new_u8,\n        np.uint16: PySeries.new_u16,\n        np.uint32: PySeries.new_u32,","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/datatypes/constructor.py#L57-L93","documentation":"polars_type_to_constructor looks up a PySeries constructor for a Polars dtype via _POLARS_TYPE_TO_CONSTRUCTOR[dtype.base_type()]; if the base type has no registered constructor a ValueError is thrown. It means polars' Rust backend cannot build a Series from Python sequences for this dtype.","triggerScenarios":"Creating a Series/Frame from a sequence whose declared dtype maps to a base type with no constructor entry — e.g. passing pl.Unknown, pl.Null used incorrectly, an unregistered custom/extension dtype, or a DataTypeInstance of an exotic category to pl.Series(..., dtype=...) / df with_columns.","commonSituations":"Using a custom extension dtype that was never registered; library-internal mapping out of sync after a polars version change; passing pl.Null or opaque nested types where a concrete dtype is required.","solutions":["Use a concrete supported dtype (pl.Int64, pl.Utf8, pl.List, pl.Array, pl.Struct, etc.) as the target dtype.","For custom types, register them via polars.datatypes.extension.register_extension_type before use.","Let polars infer the dtype instead of forcing an unsupported one, then cast afterwards with .cast()."],"exampleFix":"// before\npl.Series(\"x\", [1, 2], dtype=pl.Unknown)\n// after\npl.Series(\"x\", [1, 2])  # let polars infer, or dtype=pl.Int64","handlingStrategy":"try-catch","validationCode":"SUPPORTED_BASES = {pl.Int64, pl.Float64, pl.Utf8, pl.Boolean, pl.Date, pl.Datetime, pl.List, pl.Array, pl.Struct, pl.Binary}\nassert getattr(dtype, 'base_type', lambda: dtype)() in SUPPORTED_BASES, f\"unsupported dtype {dtype!r}\"","typeGuard":null,"tryCatchPattern":"try:\n    s = pl.Series(name, values, dtype=dtype)\nexcept ValueError as e:\n    if \"cannot construct PySeries\" in str(e):\n        s = pl.Series(name, values)  # infer, then cast\n    else:\n        raise","preventionTips":["Only force dtypes from polars' documented supported set","Register custom extension types before using them in Series","Prefer infer-then-cast over forcing exotic dtypes at construction"],"tags":["python","polars","dtype","constructor"],"backgroundTag":"unsupported-dtype","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}