pola-rs/polars · error · TypeError

`schema_overrides` should be of type list or dict, got {qual

Error message

`schema_overrides` should be of type list or dict, got {qualified_type_name(schema_overrides)!r}

What it means

In _read_csv_impl (the engine behind read_csv), schema_overrides must be a dict mapping column name to dtype, or a Sequence (list/tuple) of dtypes applied positionally to the first columns. Anything else - a bare dtype, a string like 'Int64', a set, a generator - raises this TypeError naming the offending type. The value is parsed with parse_into_dtype per entry, so each dtype must also be a valid polars dtype or string alias.

Source

Thrown at py-polars/src/polars/io/csv/functions.py:674

    else:
        path = None
        if isinstance(source, BytesIO):
            source = source.getvalue()
        if isinstance(source, StringIO):
            source = source.getvalue().encode()

    dtype_list: Sequence[tuple[str, PolarsDataType]] | None = None
    dtype_slice: Sequence[PolarsDataType] | None = None
    if schema_overrides is not None:
        if isinstance(schema_overrides, dict):
            dtype_list = []
            for k, v in schema_overrides.items():
                dtype_list.append((k, parse_into_dtype(v)))
        elif isinstance(schema_overrides, Sequence):
            dtype_slice = [parse_into_dtype(v) for v in schema_overrides]
        else:
            msg = f"`schema_overrides` should be of type list or dict, got {qualified_type_name(schema_overrides)!r}"
            raise TypeError(msg)

    processed_null_values = _process_null_values(null_values)

    if isinstance(columns, str):
        columns = [columns]
    if isinstance(source, str) and is_glob_pattern(source):
        scan_schema_overrides = (
            dict(dtype_list) if dtype_list is not None else dtype_slice
        )
        from polars import scan_csv

        scan = scan_csv(
            source,
            has_header=has_header,
            separator=separator,
            comment_prefix=comment_prefix,
            quote_char=quote_char,
            skip_rows=skip_rows,

View on GitHub (pinned to df599052da)

Solutions

Wrap a single dtype in a list: schema_overrides=[pl.Int64]
Target specific columns with a dict: schema_overrides={'user_id': pl.Int64, 'name': pl.String}
Use polars dtype objects or their exact string aliases (e.g. 'i64', 'str'); parse_into_dtype rejects arbitrary strings

Example fix

# before
pl.read_csv('users.csv', schema_overrides=pl.Int64)

# after - positional override for the first column
pl.read_csv('users.csv', schema_overrides=[pl.Int64])

# after - override by column name
pl.read_csv('users.csv', schema_overrides={'user_id': pl.Int64})

Defensive patterns

Strategy: type-guard

Validate before calling

def normalize_overrides(overrides):
    if overrides is None or isinstance(overrides, dict):
        return overrides
    if isinstance(overrides, Sequence) and not isinstance(overrides, str):
        return list(overrides)
    return [overrides]  # bare dtype -> positional single override

pl.read_csv(path, schema_overrides=normalize_overrides(user_input))

Type guard

from collections.abc import Sequence
from polars._typing import PolarsDataType

def is_valid_schema_overrides(x: object) -> bool:
    return x is None or isinstance(x, dict) or (
        isinstance(x, Sequence) and not isinstance(x, (str, bytes))
    )

Try / catch

try:
    df = pl.read_csv(path, schema_overrides=overrides)
except TypeError as err:
    if 'schema_overrides' in str(err):
        raise ValueError(f'bad schema_overrides from config: {overrides!r}') from err
    raise

Prevention

Type-annotate override variables as dict[str, PolarsDataType] | Sequence[PolarsDataType] | None so mypy catches misuse
Never pass a bare dtype or bare string; always wrap in [] or {}
When overrides come from config files, validate with isinstance checks at the config boundary, not inside read loops

When it happens

Trigger: pl.read_csv('f.csv', schema_overrides=pl.Int64); schema_overrides='Utf8' (bare string, not a Sequence); schema_overrides={pl.Int64, pl.Float64} (set is not a dict and not ordered Sequence-eligible); schema_overrides=str (a type object instead of an instance).

Common situations: Copy-paste from read_csv(schema=...) examples where a dict is expected; passing a single dtype meant for one column; migrating pandas pd.read_csv(dtype=...) calls where dtype={'col': 'int32'} got simplified to a bare value; a string being treated as a Sequence of characters would silently almost work, but a non-Sequence always fails loudly.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/844f9c880fcb487d. Report an issue: GitHub.