{"record":{"id":"697073b5b59ed115","repo":"pola-rs/polars","slug":"cannot-parse-input-input-type-into-polars-data-t","errorCode":null,"errorMessage":"cannot parse input {input_type} into Polars data type{input_detail}","messagePattern":"cannot parse input (.+?) into Polars data type(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/_parse.py","lineNumber":197,"sourceCode":"    input\n        A union type, e.g. `str | None` (new syntax) or `Union[str, None]` (old syntax).\n    \"\"\"\n    # Strip \"optional\" designation - Polars data types are always nullable\n    inner_types = [tp for tp in get_args(input) if tp is not NoneType]\n\n    if len(inner_types) != 1:\n        _raise_on_invalid_dtype(input)\n\n    input = inner_types[0]\n    return parse_into_dtype(input)\n\n\ndef _raise_on_invalid_dtype(input: Any) -> NoReturn:\n    \"\"\"Raise an informative error if the input could not be parsed.\"\"\"\n    input_type = input if type(input) is type else f\"of type {type(input).__name__!r}\"\n    input_detail = \"\" if type(input) is type else f\" (given: {input!r})\"\n    msg = f\"cannot parse input {input_type} into Polars data type{input_detail}\"\n    raise TypeError(msg) from None\n","sourceCodeStart":179,"sourceCodeEnd":198,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/datatypes/_parse.py#L179-L198","documentation":"When parsing Python type annotations into Polars dtypes, any input that is not a recognizable Polars data type reaches `_raise_on_invalid_dtype`, which raises this TypeError naming the offending input. It is the catch-all failure of the dtype-from-annotation machinery (unions, generics, forward refs included).","triggerScenarios":"Passing an unsupported annotation to APIs like `pl.DataFrame(schema=...)` with Python types, `pl.Series(dtype=...)`, or schema inference from type hints — e.g. `dtype=dict`, `dtype='Int64'` in a type-only context, or an exotic generic like `list[object]`.","commonSituations":"Using Python builtin types (`int`, `float`) or stdlib generics that Polars cannot map, typos in dtype names, or versions where a type mapping does not exist.","solutions":["Replace the annotation with a Polars dtype class (`pl.Int64`, `pl.Utf8`, `pl.List(pl.Float32)`)","Check the supported mapping in `polars.datatypes` and use matching Python types (e.g. `int`->`pl.Int64` only where supported)","Use `pl.Object` or `pl.Unknown` explicitly for untyped/foreign data","Upgrade polars if the type was recently supported"],"exampleFix":"// before\npl.DataFrame(schema={'a': dict})\n// after\npl.DataFrame(schema={'a': pl.Struct})","handlingStrategy":"validation","validationCode":"import polars as pl\nVALID = {t for t in (pl.Int64, pl.Utf8, pl.Float64, pl.Boolean, pl.List, pl.Struct)}\ndef ensure_parsable(t):\n    if t not in VALID and not hasattr(pl, getattr(t, '__name__', '')):\n        raise TypeError(f'unsupported annotation: {t!r}')","typeGuard":"def is_polars_dtype(t) -> bool:\n    import polars as pl\n    return isinstance(t, pl.DataType) or (isinstance(t, type) and issubclass(t, pl.DataType))","tryCatchPattern":"try:\n    df = pl.DataFrame(schema={'a': weird_type})\nexcept TypeError as e:\n    if 'cannot parse input' in str(e):\n        df = pl.DataFrame(schema={'a': pl.Object})\n    else:\n        raise","preventionTips":["Use pl.* dtype classes in schemas instead of raw Python types","Consult polars.datatypes for supported Python-type mappings","Use pl.Object/pl.Unknown for untypable data"],"tags":["polars","datatypes","schema","type-mismatch"],"backgroundTag":"unsupported-dtype","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}