{"record":{"id":"0301671ca0cc7db3","repo":"pola-rs/polars","slug":"invalid-sentinel-value-for-column-of-type-column","errorCode":null,"errorMessage":"invalid sentinel value for column of type {column_dtype}: {null_value!r}","messagePattern":"invalid sentinel value for column of type (.+?): (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/interchange/from_dataframe.py","lineNumber":291,"sourceCode":"    elif null_type == ColumnNullType.USE_NAN:\n        if not allow_copy:\n            msg = \"bitmask must be constructed\"\n            raise CopyNotAllowedError(msg)\n        return data.is_not_nan()\n\n    elif null_type == ColumnNullType.USE_SENTINEL:\n        if not allow_copy:\n            msg = \"bitmask must be constructed\"\n            raise CopyNotAllowedError(msg)\n\n        sentinel = pl.Series([null_value])\n        try:\n            if column_dtype.is_temporal():\n                sentinel = sentinel.cast(column_dtype)\n            return data != sentinel  # noqa: TRY300\n        except InvalidOperationError as e:\n            msg = f\"invalid sentinel value for column of type {column_dtype}: {null_value!r}\"\n            raise TypeError(msg) from e\n\n    else:\n        msg = f\"unsupported null type: {null_type!r}\"\n        raise NotImplementedError(msg)\n\n\ndef _construct_validity_buffer_from_bitmask(\n    buffer: Buffer,\n    null_value: int,\n    length: int,\n    offset: int = 0,\n    *,\n    allow_copy: bool,\n) -> Series:\n    buffer_info = (buffer.ptr, offset, length)\n    s = pl.Series._from_buffer(Boolean, buffer_info, buffer)\n\n    if null_value != 0:","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/interchange/from_dataframe.py#L273-L309","documentation":"For USE_SENTINEL null handling, Polars builds pl.Series([null_value]) and, for temporal columns, casts it to the column dtype before comparing with the data. If that cast raises InvalidOperationError, Polars re-raises it as TypeError naming the column dtype and the sentinel value. The producer advertised a sentinel that is not representable in the column's data type.","triggerScenarios":"A temporal column whose describe_null sentinel cannot be cast to that dtype - e.g. a string sentinel for a Datetime/Date column, or an integer sentinel outside the Date value range.","commonSituations":"Custom producers with mismatched sentinel metadata; porting systems where null markers were stored as strings or out-of-range codes; hand-written __dataframe__ implementations that copy sentinel values from another column type.","solutions":["Fix the producer to report a sentinel castable to the column dtype (an in-range integer for temporal types)","If the sentinel must stay as-is, import the column as its raw physical type and reconstruct nulls in Polars manually","Catch TypeError around the conversion and fall back to a manual parsing path"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"def sentinel_is_castable(df) -> bool:\n    import polars as pl\n    from polars.interchange.protocol import ColumnNullType\n    proto = df.__dataframe__(allow_copy=False)\n    for col in proto.get_columns():\n        null_type, null_value = col.describe_null()\n        if null_type == ColumnNullType.USE_SENTINEL:\n            try:\n                pl.Series([null_value])\n            except Exception:\n                return False\n    return True","typeGuard":null,"tryCatchPattern":"try:\n    out = pl.from_dataframe(df)\nexcept TypeError as e:\n    if 'invalid sentinel value' in str(e):\n        # producer sentinel metadata is wrong; import raw and fix nulls manually\n        out = pl.from_dataframe(df_raw)\n    else:\n        raise","preventionTips":["Producers: report sentinels that are representable in the column dtype (in-range integers for temporal types)","Unit-test sentinel metadata against the actual column dtypes in custom producers","Prefer explicit validity masks over sentinel nulls in any new producer code"],"tags":["polars","interchange-protocol","null-handling","sentinel","type-error","producer-bug"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}