pola-rs/polars · error · ParameterCollisionError

cannot specify columns in both `schema_overrides` and `read_

Error message

cannot specify columns in both `schema_overrides` and `read_options['dtypes']`

What it means

Raised by the xlsx2csv path of pl.read_excel (in _csv_buffer_to_frame) as a ParameterCollisionError when the top-level schema_overrides shares at least one column key with dtype overrides smuggled in read_options — either read_options['schema_overrides'] or the deprecated read_options['dtypes'] (which first triggers a deprecation warning dated 0.20.31). Only the key SET intersection matters: disjoint dicts are merged without error. Note ParameterCollisionError subclasses PolarsError, not ValueError.

Source

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

    csv.seek(0)

    if read_options is None:
        read_options = {}

    date_cols = []
    if schema_overrides:
        if csv_dtypes := read_options.get("dtypes", {}):
            issue_deprecation_warning(
                "the `dtypes` parameter for `read_csv` is deprecated. It has been renamed to `schema_overrides`.",
                version="0.20.31",
            )

        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

    df = _drop_null_data(
        df=read_csv(
            csv,
            separator=separator,
            **read_options,
        ),
        raise_if_empty=raise_if_empty,

View on GitHub (pinned to df599052da)

Solutions

1. Consolidate ALL column type overrides into the top-level schema_overrides parameter
2. Remove 'dtypes' (deprecated) and 'schema_overrides' keys from read_options entirely
3. Keep read_options for csv-mechanics keys only (separator, skip_rows, truncate_ragged_lines, ...)

Example fix

# before
pl.read_excel(src, engine='xlsx2csv', schema_overrides={'id': pl.Int64}, read_options={'dtypes': {'id': pl.Float64}})

# after
pl.read_excel(src, engine='xlsx2csv', schema_overrides={'id': pl.Int64})

opts = dict(read_options or {})
inline_overrides = set(opts.pop('dtypes', {})) | set(opts.pop('schema_overrides', {}))
if inline_overrides & set(schema_overrides or {}):
    raise ValueError('same column overridden in both schema_overrides and read_options')
# merge once, top-level only
schema_overrides = {**{k: v for k, v in read_options.get('dtypes', {}).items()}, **(schema_overrides or {})}
df = pl.read_excel(src, engine='xlsx2csv', schema_overrides=schema_overrides, read_options=opts)

from polars.exceptions import ParameterCollisionError
try:
    df = pl.read_excel(src, engine='xlsx2csv', schema_overrides=ov, read_options=opts)
except ParameterCollisionError as e:
    if 'schema_overrides' in str(e):
        opts.pop('dtypes', None); opts.pop('schema_overrides', None)
        df = pl.read_excel(src, engine='xlsx2csv', schema_overrides=ov, read_options=opts)
    else:
        raise

When it happens

Trigger: pl.read_excel(src, engine='xlsx2csv', schema_overrides={'a': pl.Int64}, read_options={'dtypes': {'a': pl.Float64}}) or read_options={'schema_overrides': {'a': pl.Int64}} — any overlap of column names between the two layers raises.

Common situations: Copy-pasting read_csv(..., dtypes=...) kwargs into read_options while also using polars' schema_overrides parameter; older tutorials that used read_options['dtypes']; central config dicts that carry csv dtype maps.

Related errors

• cannot specify both `columns` and `read_options["columns"]`
• the values of `has_header` and `read_options["has_header"]`
• cannot specify both `infer_schema_length` and `read_options[
• the `table_name` parameter is not supported by the 'xlsx2csv
• `strict` cannot be used with `how='horizontal_extend'`

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