{"record":{"id":"fee533d281f1f287","repo":"pola-rs/polars","slug":"cannot-convert-python-type-qualified-type-name-el","errorCode":null,"errorMessage":"cannot convert Python type {qualified_type_name(el)!r} to {dtype!r}","messagePattern":"cannot convert Python type (.+?) to (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/convert.py","lineNumber":357,"sourceCode":"    )\n\n    time_unit: TimeUnit\n    if isinstance(el, datetime):\n        time_unit = getattr(dtype, \"time_unit\", \"us\")\n        return datetime_to_int(el, time_unit)\n    elif isinstance(el, timedelta):\n        time_unit = getattr(dtype, \"time_unit\", \"us\")\n        return timedelta_to_int(el, time_unit)\n\n    py_type = dtype_to_py_type(dtype)\n    if not isinstance(el, py_type):\n        try:\n            el = py_type(el)  # type: ignore[call-arg]\n        except Exception:\n            from polars._utils.various import qualified_type_name\n\n            msg = f\"cannot convert Python type {qualified_type_name(el)!r} to {dtype!r}\"\n            raise TypeError(msg) from None\n    return el\n","sourceCodeStart":339,"sourceCodeEnd":359,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/datatypes/convert.py#L339-L359","documentation":"maybe_cast coerces a single Python value to something valid for a target polars dtype. It maps the dtype to a Python type and calls py_type(el); if that constructor call fails (e.g. int('abc')), the failure is re-raised as TypeError naming both the value's type and the target dtype. It means the value cannot be constructed into the dtype's Python equivalent at all.","triggerScenarios":"maybe_cast('not-a-number', pl.Int64), maybe_cast(object(), pl.Datetime), or row/element construction paths where a Python value for one column is fundamentally incompatible with the column's dtype (string into a numeric dtype, non-temporal object into Datetime).","commonSituations":"Building Series/DataFrames from heterogeneous rows where a stray string lands in a numeric column; pre-parsed JSON/CSV values with wrong types; custom objects expected to auto-convert.","solutions":["Clean or convert offending values before construction (parse to int/float/datetime yourself)","Load the dirty column as pl.String first, then .cast(target, strict=False) so bad values become nulls instead of raising","Validate per-column value types before building the Series/DataFrame"],"exampleFix":"# before\ns = pl.Series('n', ['1', 'oops', '3']).cast(pl.Int64)  # hits conversion error paths\n\n# after\ns = pl.Series('n', ['1', 'oops', '3']).cast(pl.Int64, strict=False)  # null for 'oops'","handlingStrategy":"try-catch","validationCode":"from polars.datatypes.convert import dtype_to_py_type\n\ndef can_cast_value(el, dtype) -> bool:\n    try:\n        py_type = dtype_to_py_type(dtype)\n    except NotImplementedError:\n        return True  # nested dtypes handled separately\n    if isinstance(el, py_type):\n        return True\n    try:\n        py_type(el)\n        return True\n    except Exception:\n        return False\n\nassert can_cast_value(el, dtype), f'value {el!r} incompatible with {dtype!r}'","typeGuard":null,"tryCatchPattern":"from polars.datatypes.convert import maybe_cast\n\ntry:\n    v = maybe_cast(el, dtype)\nexcept TypeError:\n    v = None  # or collect the row index and report a data-quality error","preventionTips":["Load dirty columns as String and .cast(strict=False) to surface bad values as nulls","Pre-validate row values against the column's Python type before Series construction"],"tags":["dtype","value-conversion","typeerror","data-quality"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}