What causes "unsupported data type: {dtype}" in pola-rs/polars?

Drop or cast unsupported columns before export (Binary -> String, fill Null columns with a concrete dtype, flatten nested columns)

pola-rs/polars · error · NotImplementedError

unsupported data type: {dtype}

Error message

unsupported data type: {dtype}

What it means

polars_dtype_to_data_buffer_dtype decides the physical buffer dtype on the export path: integers/floats/booleans map to themselves, temporal types to Int32 (Date) or Int64, String to UInt8, and Enum/Categorical to UInt32. Any other Polars dtype - Binary, Null, Object, or nested types - has no data-buffer representation, so the function raises NotImplementedError.

Source

Thrown at py-polars/src/polars/interchange/utils.py:173

    if rest > 0:
        msg = f"cannot get buffer length for buffer with dtype {dtype!r}"
        raise ValueError(msg)
    return buffer_size // bytes_per_element


def polars_dtype_to_data_buffer_dtype(dtype: PolarsDataType) -> PolarsDataType:
    """Get the data type of the data buffer."""
    if dtype.is_integer() or dtype.is_float() or dtype == Boolean:
        return dtype
    elif dtype.is_temporal():
        return Int32 if dtype == Date else Int64
    elif dtype == String:
        return UInt8
    elif dtype in (Enum, Categorical):
        return UInt32

    msg = f"unsupported data type: {dtype}"
    raise NotImplementedError(msg)

View on GitHub (pinned to df599052da)

Solutions

Drop or cast unsupported columns before export (Binary -> String, fill Null columns with a concrete dtype, flatten nested columns)
Select only protocol-supported columns before handing the frame to an interchange consumer
Use df.to_arrow() for full-fidelity transfer including nested and binary types

Example fix

// before
df.__dataframe__()  # contains Binary/Null column -> NotImplementedError

// after
df = df.with_columns(
    pl.col('payload').cast(pl.String),        # Binary -> String
    pl.col('maybe').fill_null(0),              # Null -> concrete dtype
)
df.select(exportable_cols).__dataframe__()

Defensive patterns

Strategy: validation

Validate before calling

import polars as pl
from polars.interchange.utils import polars_dtype_to_data_buffer_dtype

def columns_have_buffer_representation(df: pl.DataFrame) -> list[str]:
    bad = []
    for name, dtype in zip(df.columns, df.dtypes):
        try:
            polars_dtype_to_data_buffer_dtype(dtype)
        except NotImplementedError:
            bad.append(name)
    return bad

# usage: assert not columns_have_buffer_representation(df) before export

Try / catch

try:
    proto = df.__dataframe__()
except NotImplementedError as e:
    if 'unsupported data type' in str(e):
        bad = columns_have_buffer_representation(df)
        raise ValueError(f'columns without interchange buffers: {bad}') from e
    raise

Prevention

Cast Binary to String, fill Null columns with concrete dtypes, and flatten nested columns before interchange export
Watch for schema drift after concat/join operations that introduce Null-typed columns
Use df.to_arrow() when Binary or nested data must be preserved end to end

When it happens

Trigger: Exporting a Polars DataFrame containing Binary, Null, Object, or nested (List/Struct/Array) columns through the interchange protocol, i.e. when a consumer walks df.__dataframe__() and reads column buffers.

Common situations: Schemas grown via concat or joins that introduced Null-typed columns; Binary payload columns (hashes, encoded blobs) reaching an interchange consumer; nested aggregations passed through unchanged.

Related errors

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