pola-rs/polars · error · TypeError

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

Error message

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

What it means

Internally, after the initial validation, `scan_csv` normalizes `schema_overrides` entries via `parse_into_dtype`. If the argument survives the dict/Sequence isinstance checks but is neither — reaching this final else — polars raises this TypeError reporting the qualified type name of the offending value. It is a defensive, more detailed version of the earlier `schema_overrides` type error.

Solutions

1. Convert the value to a plain dict or list before the call: `dict(schema_overrides)` or `list(...)`.
2. Ensure values inside the container are dtype-convertible (they are parsed with `parse_into_dtype`).
3. Add a pre-call assertion: `assert isinstance(so, (dict, list, tuple))`.

Example fix

// before
pl.scan_csv("f.csv", schema_overrides={"a", "b"})  # set
// after
pl.scan_csv("f.csv", schema_overrides=list(schema_overrides_set))

def is_overrides_container(so) -> bool:
    from collections.abc import Sequence
    return isinstance(so, (dict, Sequence)) and not isinstance(so, (str, bytes, set))

try:
    lf = pl.scan_csv(src, schema_overrides=so)
except TypeError as e:
    if "schema_overrides" in str(e):
        lf = pl.scan_csv(src, schema_overrides=dict(so))
    else:
        raise

When it happens

Trigger: Calling `pl.scan_csv` with a `schema_overrides` object that is not a dict or Sequence (e.g. a set, a custom mapping, a scalar dtype) reaching the normalization branch, typically via `_scan` forwarding.

Common situations: Custom dict-like classes not inheriting from dict; passing frozenset or numpy scalar types; dynamically constructed kwargs with wrong shapes.

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

• cannot set both `with_column_names` and `new_columns`…
• cannot set truncate_ragged_lines=False with…
• `schema_overrides` should be of type list or dict
• =" " should be a single byte character or empty, but is…
• =" " should be a single byte character, but is bytes long

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

Appendix: source

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

        issue_unstable_warning(msg)

    credential_provider_builder = _init_credential_provider_builder(
        credential_provider, source, storage_options, "scan_csv"
    )
    del credential_provider

    dtype_list: list[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(source, list):
        sources = source
        source = None  # type: ignore[assignment]
    else:
        sources = []

    pylf = PyLazyFrame.new_from_csv(
        source,
        sources,
        separator=separator,
        has_header=has_header,
        ignore_errors=ignore_errors,
        skip_rows=skip_rows,
        skip_lines=skip_lines,
        n_rows=n_rows,
        overwrite_dtype=dtype_list,

View on GitHub (pinned to fe841f959e)