pola-rs/polars · error

cannot parse input into Polars data type

Error message

cannot parse input {input_type} into Polars data type{input_detail}

What it means

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).

Solutions

1. Replace the annotation with a Polars dtype class (`pl.Int64`, `pl.Utf8`, `pl.List(pl.Float32)`)
2. Check the supported mapping in `polars.datatypes` and use matching Python types (e.g. `int`->`pl.Int64` only where supported)
3. Use `pl.Object` or `pl.Unknown` explicitly for untyped/foreign data
4. Upgrade polars if the type was recently supported

Example fix

// before
pl.DataFrame(schema={'a': dict})
// after
pl.DataFrame(schema={'a': pl.Struct})

import polars as pl
VALID = {t for t in (pl.Int64, pl.Utf8, pl.Float64, pl.Boolean, pl.List, pl.Struct)}
def ensure_parsable(t):
    if t not in VALID and not hasattr(pl, getattr(t, '__name__', '')):
        raise TypeError(f'unsupported annotation: {t!r}')

def is_polars_dtype(t) -> bool:
    import polars as pl
    return isinstance(t, pl.DataType) or (isinstance(t, type) and issubclass(t, pl.DataType))

try:
    df = pl.DataFrame(schema={'a': weird_type})
except TypeError as e:
    if 'cannot parse input' in str(e):
        df = pl.DataFrame(schema={'a': pl.Object})
    else:
        raise

When it happens

Trigger: 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]`.

Common situations: 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.

Related errors

• `arctan2` expected a `str` or `Expr` got a
• `arctan2` expected a `str` or `Expr` got a
• can only convert date/datetime to NaiveDateTime
• can only convert date/datetime to NaiveTime
• can't convert to Decimal

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/697073b5b59ed115. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/datatypes/_parse.py:197

    input
        A union type, e.g. `str | None` (new syntax) or `Union[str, None]` (old syntax).
    """
    # Strip "optional" designation - Polars data types are always nullable
    inner_types = [tp for tp in get_args(input) if tp is not NoneType]

    if len(inner_types) != 1:
        _raise_on_invalid_dtype(input)

    input = inner_types[0]
    return parse_into_dtype(input)


def _raise_on_invalid_dtype(input: Any) -> NoReturn:
    """Raise an informative error if the input could not be parsed."""
    input_type = input if type(input) is type else f"of type {type(input).__name__!r}"
    input_detail = "" if type(input) is type else f" (given: {input!r})"
    msg = f"cannot parse input {input_type} into Polars data type{input_detail}"
    raise TypeError(msg) from None

View on GitHub (pinned to fe841f959e)