pola-rs/polars · error · NotImplementedError

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

Error message

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

What it means

dtype_to_py_type converts a polars dtype to the corresponding Python scalar type, but the mapping only covers primitive dtypes. Nested types (List, Array, Struct) have no single Python equivalent, so lookup raises NotImplementedError. Usually hit indirectly through generic code that assumes every dtype maps to one Python type.

Source

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

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 df599052da)

Solutions

1. Handle nested dtypes explicitly: branch on isinstance(dtype, (pl.List, pl.Array, pl.Struct)) and recurse into inner types instead of calling dtype_to_py_type
2. Upgrade polars — dtype mappings gain coverage across releases
3. If you cannot avoid the call, catch NotImplementedError and fall back to object-level handling for that column

Example fix

# before
py_type = dtype_to_py_type(pl.List(pl.Int64))  # NotImplementedError

# after
if isinstance(dtype, (pl.List, pl.Array, pl.Struct)):
    py_type = object  # handle inner types yourself
else:
    py_type = dtype_to_py_type(dtype)

import polars as pl

def is_nested_dtype(dtype: pl.DataType) -> bool:
    return isinstance(dtype, (pl.List, pl.Array, pl.Struct))

# guard before scalar conversion
if not is_nested_dtype(dtype):
    py_type = dtype_to_py_type(dtype)

from polars.datatypes.convert import dtype_to_py_type

try:
    py_type = dtype_to_py_type(dtype)
except NotImplementedError:
    py_type = object  # nested dtype: handle inner fields explicitly

When it happens

Trigger: Calling polars.datatypes.convert.dtype_to_py_type (directly or via maybe_cast-style item conversion) with pl.List(pl.Int64), pl.Array(pl.String, 3), pl.Struct([...]), or another dtype whose base_type() is absent from DTYPE_TO_PY_TYPE.

Common situations: Serialising polars schemas to Python type hints; generic dtype-walking utilities over DataFrames that contain list/struct columns; item conversion helpers reaching nested columns.

Related errors

• incorrect NumPy datetime resolution 'D' (datetime only), 'm
• conversion of polars data type {dtype!r} to FFI not implemen
• cannot parse numpy data type {dtype!r} into Polars data type
• unsupported data type: {dtype!r}
• unsupported data type: {dtype}

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