pola-rs/polars · error · NotImplementedError

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

Error message

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

What it means

The internal helper dtype_to_ffiname maps a polars dtype to its Rust-side FFI constructor name. If the dtype's base_type() has no entry in DTYPE_TO_FFINAME, NotImplementedError is raised. This mapping only covers known primitive dtypes, so custom extension dtypes or dtypes newer than the installed polars version fail here.

Source

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

            str_repr: obj
            for obj in globals().values()
            if is_polars_dtype(obj)
            and (str_repr := _dtype_str_repr_safe(obj)) is not None
        }


# Initialize once (poor man's singleton :)
DataTypeMappings: Final[_DataTypeMappings] = _DataTypeMappings()


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"

View on GitHub (pinned to df599052da)

Solutions

  1. Upgrade polars (and any companion packages) to matching versions so every dtype in use has an FFI mapping
  2. Avoid feeding custom or newly-introduced dtypes into internal FFI conversion paths; stick to supported primitive dtypes
  3. If you call dtype_to_ffiname directly, catch NotImplementedError and degrade to a supported representation
Defensive patterns

Strategy: try-catch

Validate before calling

from polars.datatypes import convert

def has_ffiname(dtype) -> bool:
    try:
        convert.dtype_to_ffiname(dtype)
        return True
    except NotImplementedError:
        return False

assert has_ffiname(dtype), f'no FFI mapping for {dtype!r}'

Try / catch

from polars.datatypes.convert import dtype_to_ffiname

try:
    ffi_name = dtype_to_ffiname(dtype)
except NotImplementedError:
    # dtype too new or custom: degrade or reject explicitly
    raise ValueError(f'unsupported dtype for FFI: {dtype!r}; upgrade polars') from None

Prevention

When it happens

Trigger: Internal or third-party code (e.g. polars-optimizer plugins, meta/bridging code, or direct calls to polars.datatypes.convert.dtype_to_ffiname) encounters a dtype absent from the mapping — typically a custom extension dtype or one introduced in a different polars version.

Common situations: Version skew between polars and companion packages where a new dtype exists on one side only; user-registered extension types without FFI support; code calling polars' private convert API directly.

Related errors

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