pola-rs/polars · error · TypeError

the `dtypes` parameter for `read_csv` has been renamed to `s

Error message

the `dtypes` parameter for `read_csv` has been renamed to `schema_overrides`.

What it means

TypeError raised in polars' spreadsheet (Excel) reading path when read_options passed to read_excel still contains the legacy 'dtypes' key. That key was renamed to 'schema_overrides' in the embedded read_csv options, so its presence signals pre-migration code and is rejected with instructions.

Source

Thrown at py-polars/src/polars/io/spreadsheet/functions.py:930

    drop_empty_cols: bool,
    raise_if_empty: bool,
) -> pl.DataFrame:
    """Translate StringIO buffer containing delimited data as a DataFrame."""
    # handle (completely) empty sheet data
    if csv.tell() == 0:
        return _empty_frame(raise_if_empty)

    # otherwise rewind the buffer and parse as csv
    csv.seek(0)

    if read_options is None:
        read_options = {}

    date_cols = []
    if schema_overrides:
        if csv_dtypes := read_options.get("dtypes", {}):
            msg = "the `dtypes` parameter for `read_csv` has been renamed to `schema_overrides`."
            raise TypeError(msg)

        csv_schema_overrides = cast(
            "SchemaDict", read_options.get("schema_overrides", csv_dtypes)
        )
        if set(csv_schema_overrides).intersection(schema_overrides):
            msg = "cannot specify columns in both `schema_overrides` and `read_options['dtypes']`"
            raise ParameterCollisionError(msg)

        overrides, schema_overrides = {**csv_schema_overrides, **schema_overrides}, {}
        for nm, dtype in overrides.items():
            if dtype != Date:
                schema_overrides[nm] = dtype
            else:
                date_cols.append(nm)

        read_options = read_options.copy()
        read_options["schema_overrides"] = schema_overrides

View on GitHub (pinned to 5d8ebabf11)

Solutions

1. Rename the key: read_options={'schema_overrides': {...}}
2. Prefer the top-level schema_overrides parameter of read_excel itself
3. Remove any leftover 'dtypes' entries when merging option dicts

Example fix

# before
pl.read_excel('f.xlsx', read_options={'dtypes': {'a': pl.Int64}})
# after
pl.read_excel('f.xlsx', read_options={'schema_overrides': {'a': pl.Int64}})

if 'dtypes' in read_options:
    read_options['schema_overrides'] = read_options.pop('dtypes')

When it happens

Trigger: pl.read_excel('f.xlsx', read_options={'dtypes': {...}}) — passing old-style read_csv options through the xlsx2csv bridge (the _csv_buffer_to_frame path).

Common situations: Upgrading code that previously tuned CSV dtypes when reading Excel; copy-pasting read_csv option dicts into read_excel read_options.

Related errors

• `{name}` was removed in version {version}
• {func_name!r} received both {param.name!r} and {param.new_na
• the argument {param.name!r} for {func_name!r}{was_deprecated
• the argument {param.name!r} for {func_name!r}{was_deprecated
• `strict=False` is no longer supported for `how='horizontal'`

AI-assisted analysis of pola-rs/polars@5d8ebabf11 (2026-08-28). Data as JSON: /api/errors/c66d23bea4398c79. Report an issue: GitHub.