pola-rs/polars · error · TypeError

`schema_overrides` should be of type list or dict

Error message

`schema_overrides` should be of type list or dict

What it means

The `schema_overrides` argument of `read_csv` accepts only a dict mapping column names to dtypes, or a sequence (list) of dtypes. `_read_csv` validates the argument type up front and raises this TypeError for anything else (e.g. a single dtype, a string, a tuple of mixed content, or a set).

Solutions

1. Wrap a single dtype in a list: `schema_overrides=[pl.Int64]`.
2. Use a dict keyed by column name for targeted overrides: `schema_overrides={"id": pl.Utf8}`.
3. Ensure the value is a real `dict` or `Sequence` (tuple/list), not a generator or set.
4. Migrate from the legacy `dtype=` parameter name to `schema_overrides=`.

Example fix

// before
pl.read_csv("f.csv", schema_overrides=pl.Int64)
# after
pl.read_csv("f.csv", schema_overrides={"id": pl.Int64})

from collections.abc import Sequence
def is_valid_schema_overrides(so) -> bool:
    return so is None or isinstance(so, (dict, Sequence)) and not isinstance(so, (str, bytes))

try:
    df = pl.read_csv(path, schema_overrides=so)
except TypeError as e:
    if "schema_overrides" in str(e):
        so = [so]  # wrap single dtype
        df = pl.read_csv(path, schema_overrides=so)
    else:
        raise

When it happens

Trigger: `pl.read_csv(..., schema_overrides=str)` or passing an int/set/single pl.DataType object, or a non-iterable object instead of a list/dict of dtypes.

Common situations: Confusing `schema_overrides` with `schema` (which expects different shapes); passing one dtype intending it to apply to all columns; passing a dict-like custom mapping that isn't a dict instance; older code using the removed `dtype` parameter name.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• `schema_overrides` should be of type list or dict, got
• specified column names do not start with 'column_', but…
• =" " should be a single byte character or empty, but is…
• =" " should be a single byte character, but is bytes long
• arr.to_struct() got a str instead of a list. hint: pass

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

Appendix: source

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

    _check_arg_is_1byte("quote_char", quote_char, can_be_empty=True)
    _check_arg_is_1byte("eol_char", eol_char, can_be_empty=False)

    storage_options = storage_options or {}

    if column_names and not has_header:
        for column in column_names:
            if not column.startswith("column_"):
                msg = (
                    "specified column names do not start with 'column_',"
                    " but autogenerated header names were requested"
                )
                raise ValueError(msg)

    if schema_overrides is not None and not isinstance(
        schema_overrides, (dict, Sequence)
    ):
        msg = "`schema_overrides` should be of type list or dict"
        raise TypeError(msg)

    if raise_if_empty is None:
        raise_if_empty = schema is None or has_header

    if (
        use_pyarrow
        and schema_overrides is None
        and n_rows is None
        and not low_memory
        and null_values is None
        and with_column_names is None
        and credential_provider == "auto"
        and include_file_paths is None
    ):
        include_columns: Sequence[str] | None = None
        if column_names:
            if not has_header:
                # Convert 'column_0', 'column_1', ... column names to 'f0', 'f1', ...

View on GitHub (pinned to fe841f959e)