{"record":{"id":"b3979176a8371a06","repo":"pola-rs/polars","slug":"unsupported-temporal-data-type-dtype-r","errorCode":null,"errorMessage":"unsupported temporal data type: {dtype!r}","messagePattern":"unsupported temporal data type: (.+?)","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/interchange/utils.py","lineNumber":148,"sourceCode":"\ndef _temporal_dtype_to_polars_dtype(format_str: str, dtype: Dtype) -> PolarsDataType:\n    if (match := re.fullmatch(r\"ts([mun]):(.*)\", format_str)) is not None:\n        time_unit = match.group(1) + \"s\"\n        time_zone = match.group(2) or None\n        return Datetime(\n            time_unit=time_unit,  # type: ignore[arg-type]\n            time_zone=time_zone,\n        )\n    elif format_str == \"tdD\":\n        return Date\n    elif format_str == \"ttu\":\n        return Time\n    elif (match := re.fullmatch(r\"tD([mun])\", format_str)) is not None:\n        time_unit = match.group(1) + \"s\"\n        return Duration(time_unit=time_unit)  # type: ignore[arg-type]\n\n    msg = f\"unsupported temporal data type: {dtype!r}\"\n    raise NotImplementedError(msg)\n\n\ndef get_buffer_length_in_elements(buffer_size: int, dtype: Dtype) -> int:\n    \"\"\"Get the length of a buffer in elements.\"\"\"\n    bits_per_element = dtype[1]\n    bytes_per_element, rest = divmod(bits_per_element, 8)\n    if rest > 0:\n        msg = f\"cannot get buffer length for buffer with dtype {dtype!r}\"\n        raise ValueError(msg)\n    return buffer_size // bytes_per_element\n\n\ndef polars_dtype_to_data_buffer_dtype(dtype: PolarsDataType) -> PolarsDataType:\n    \"\"\"Get the data type of the data buffer.\"\"\"\n    if dtype.is_integer() or dtype.is_float() or dtype == Boolean:\n        return dtype\n    elif dtype.is_temporal():\n        return Int32 if dtype == Date else Int64","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/interchange/utils.py#L130-L166","documentation":"Temporal protocol dtypes are recognized purely by their format string: 'ts<m|u|n>:<tz>' for datetimes, 'tdD' for dates, 'ttu' for times, and 'tD<m|u|n>' for durations. Any other format string falls through all branches and raises NotImplementedError with the offending dtype shown. The producer emitted a temporal encoding polars cannot parse.","triggerScenarios":"A producer emitting a non-standard or malformed temporal format string, e.g. 'tsa:...' (attoseconds), 'tdW' (weeks), or a misspelled variant.","commonSituations":"Hand-rolled producers with typo'd format strings; draft or extended spec encodings; unit mismatches after a producer changes its temporal representation.","solutions":["Fix the producer to emit one of the supported format strings (ts[mun]:tz, tdD, ttu, tD[mun])","Expose the column as plain integers upstream and build the Datetime/Duration in Polars afterwards with cast","Upgrade polars if the format string was added in a newer release"],"exampleFix":"// producer-side fix: emit 'tsu:UTC' instead of 'tsa:UTC'\n// consumer-side workaround: import as Int64 and cast\ndf = pl.from_dataframe(raw_df).with_columns(pl.col('ts').cast(pl.Datetime('us', 'UTC')))","handlingStrategy":"try-catch","validationCode":"import re\n\nSUPPORTED_TEMPORAL = re.compile(r'^(ts[mun]:.*|tdD|ttu|tD[mun])$')\n\ndef temporal_format_supported(format_str: str) -> bool:\n    return SUPPORTED_TEMPORAL.fullmatch(format_str) is not None","typeGuard":null,"tryCatchPattern":"try:\n    out = pl.from_dataframe(df)\nexcept NotImplementedError as e:\n    if 'unsupported temporal data type' in str(e):\n        raise ValueError(\n            'producer emits a temporal format string polars cannot parse; '\n            'use ts[mun]:tz / tdD / ttu / tD[mun] or export raw integers'\n        ) from e\n    raise","preventionTips":["Producers: stick to the supported format strings (ts[mun]:tz, tdD, ttu, tD[mun])","When in doubt, export temporal data as plain integers and cast in polars to Datetime/Duration","Add schema contract tests that validate format strings whenever a producer changes temporal units"],"tags":["polars","interchange-protocol","temporal","datetime","not-implemented","producer-bug"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}