pola-rs/polars · error · NotImplementedError

conversion of polars data type

Error message

conversion of polars data type {dtype!r} to Python type not implemented

What it means

dtype_to_py_type maps a Polars dtype to its corresponding Python type (int, float, str, ...) via DTYPE_TO_PY_TYPE; unmapped dtypes raise NotImplementedError. Called when polars needs to coerce values to Python objects matching the column dtype (to_python, maybe_cast, sequence conversion).

Solutions

Cast to a mapped dtype first: s.cast(pl.Utf8) for categorical/enum before to_list().
Use .to_dicts() or .rows() for struct/nested data instead of per-dtype conversion.
Upgrade polars if a recently added dtype lacks the mapping in your version.

Example fix

// before
s.to_python()  # s.dtype == pl.Enum
// after
s.cast(pl.Utf8).to_python()

Defensive patterns

Strategy: try-catch

Validate before calling

from polars.datatypes.convert import dtype_to_py_type
def python_convertible(dtype) -> bool:
    try:
        dtype_to_py_type(dtype)
        return True
    except NotImplementedError:
        return False

Try / catch

try:
    vals = s.to_python()
except NotImplementedError:
    vals = s.cast(pl.Utf8).to_python()  # or use to_dicts()/rows() for nested types

Prevention

Cast categorical/enum/binary columns to base dtypes before python conversion
Use to_dicts() or rows() for struct and nested columns
Check the DTYPE_TO_PY_TYPE mapping when introducing new dtypes

When it happens

Trigger: Series.to_python()/to_list() paths on dtypes without a Python analogue (pl.Struct in some paths, pl.Categorical, pl.Enum, pl.Binary on old versions, custom dtypes); strict casting in sequence_to_pyseries.

Common situations: Converting a categorical/enum column expecting plain Python types; iterating over nested struct columns through the python-conversion API; custom extension dtypes not registered in the mapping.

Related errors

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

Appendix: source

Thrown at py-polars/src/polars/datatypes/convert.py:279

def dtype_to_ffiname(dtype: PolarsDataType) -> str:
    """Return FFI function name associated with the given Polars dtype."""
    try:
        dtype = dtype.base_type()
        return DataTypeMappings.DTYPE_TO_FFINAME[dtype]
    except KeyError:  # pragma: no cover
        msg = f"conversion of polars data type {dtype!r} to FFI not implemented"
        raise NotImplementedError(msg) from None


def dtype_to_py_type(dtype: PolarsDataType) -> PythonDataType:
    """Convert a Polars dtype to a Python dtype."""
    try:
        dtype = dtype.base_type()
        return DataTypeMappings.DTYPE_TO_PY_TYPE[dtype]
    except KeyError:  # pragma: no cover
        msg = f"conversion of polars data type {dtype!r} to Python type not implemented"
        raise NotImplementedError(msg) from None


def py_type_to_arrow_type(dtype: PythonDataType) -> pa.DataType:
    """Convert a Python dtype to an Arrow dtype."""
    try:
        return DataTypeMappings.PY_TYPE_TO_ARROW_TYPE[dtype]
    except KeyError:  # pragma: no cover
        msg = f"cannot parse Python data type {dtype!r} into Arrow data type"
        raise ValueError(msg) from None


def dtype_short_repr_to_dtype(dtype_string: str | None) -> PolarsDataType | None:
    """Map a PolarsDataType short repr (eg: 'i64', 'list[str]') back into a dtype."""
    if dtype_string is None:
        return None

    m = re.match(r"^(\w+)(?:\[(.+)\])?$", dtype_string)
    if m is None:

View on GitHub (pinned to fe841f959e)