pola-rs/polars · error · NotImplementedError

unsupported temporal data type

Error message

unsupported temporal data type: {dtype!r}

What it means

Temporal interchange dtypes are recognized by their format string: 'ts<m|u|n>:<tz>' -> Datetime, 'tdD' -> Date, 'ttu' -> Time, 'tD<m|u|n>' -> Duration. Any other DATETIME-kind format string — e.g. second-precision timestamps ('tss:...'), or an unrecognized unit — raises NotImplementedError('unsupported temporal data type: ...').

Solutions

  1. Change the producer to emit millisecond/microsecond/nanosecond units ('tsm:'/'tsu:'/'tsn:') or 'tdD'/'ttu'.
  2. Convert the columns to a supported representation on the producer (e.g. int64 microseconds, or a pyarrow timestamp with us unit).
  3. Catch NotImplementedError and import the offending column through the Arrow path instead.

Example fix

# producer side, before
 return (DtypeKind.DATETIME, 64, "tss:UTC", "=")  # seconds -> NotImplementedError
# after
 return (DtypeKind.DATETIME, 64, "tsu:UTC", "=")  # microseconds, supported
Defensive patterns

Strategy: try-catch

Validate before calling

import re

SUPPORTED_TEMPORAL = re.compile(r"^(ts[mun]:.*|tdD|ttu|tD[mun])$")

bad = [
    (i, icdf.get_column(i).dtype)
    for i in range(icdf.num_columns())
    if icdf.get_column(i).dtype[0] == DtypeKind.DATETIME
    and not SUPPORTED_TEMPORAL.fullmatch(icdf.get_column(i).dtype[2])
]

Try / catch

try:
    df = pl.from_dataframe(obj)
except NotImplementedError as e:
    if "unsupported temporal data type" not in str(e):
        raise
    # re-express the column on the producer in 'tsu:'/'tdD'/'ttu', then retry

Prevention

When it happens

Trigger: pl.from_dataframe(obj) where a producer declares temporal columns with format strings outside the recognized set, most notably second-unit timestamps ('tss:UTC') or hour/week durations ('tDh').

Common situations: Producers whose native clock granularity is seconds (databases, some scientific formats); custom interchange adapters hand-building Dtype tuples and guessing the format-string grammar; newer protocol producers adding units Polars does not map.

Related errors

AI-assisted analysis of pola-rs/polars@9b5d73fd00 (2026-08-19). Data as JSON: /api/errors/b3979176a8371a06. Report an issue: GitHub.

Appendix: source

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

def _temporal_dtype_to_polars_dtype(format_str: str, dtype: Dtype) -> PolarsDataType:
    if (match := re.fullmatch(r"ts([mun]):(.*)", format_str)) is not None:
        time_unit = match.group(1) + "s"
        time_zone = match.group(2) or None
        return Datetime(
            time_unit=time_unit,  # type: ignore[arg-type]
            time_zone=time_zone,
        )
    elif format_str == "tdD":
        return Date
    elif format_str == "ttu":
        return Time
    elif (match := re.fullmatch(r"tD([mun])", format_str)) is not None:
        time_unit = match.group(1) + "s"
        return Duration(time_unit=time_unit)  # type: ignore[arg-type]

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


def get_buffer_length_in_elements(buffer_size: int, dtype: Dtype) -> int:
    """Get the length of a buffer in elements."""
    bits_per_element = dtype[1]
    bytes_per_element, rest = divmod(bits_per_element, 8)
    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

View on GitHub (pinned to 9b5d73fd00)