pola-rs/polars · error · ParameterCollisionError

cannot specify both `columns` and…

Error message

cannot specify both `columns` and `read_options["use_columns"]`

What it means

In `read_excel`, passing `columns` as a top-level argument while also supplying `read_options["use_columns"]` creates a conflict: the function derives `use_columns` from `columns` and refuses to overwrite a user-specified value. Polars raises `ParameterCollisionError` to prevent ambiguous intent about which columns to read.

Solutions

  1. Remove `use_columns` from `read_options` and pass columns only via the top-level `columns=` argument
  2. Or remove the `columns=` argument and keep `read_options={"use_columns": [...]}`
  3. Do not merge both config styles; pick one canonical way per call

Example fix

// before
pl.read_excel(f, columns=['a','b'], read_options={'use_columns': 'A:B'})
// after
pl.read_excel(f, columns=['a','b'])
Defensive patterns

Strategy: validation

Validate before calling

assert not ('use_columns' in read_options and columns), 'pass columns= or read_options[use_columns], not both'

Try / catch

from polars.exceptions import ParameterCollisionError
try:
    pl.read_excel(f, columns=cols, read_options=ro)
except ParameterCollisionError as e:
    ro.pop('use_columns', None)
    df = pl.read_excel(f, columns=cols, read_options=ro)

Prevention

When it happens

Trigger: Calling `pl.read_excel(source, columns=[...])` with an engine (fastexcel/xlsx2csv path) whose `read_options` dict also contains `use_columns`; in `_get_read_options` for the non-xlsx2csv engine branch.

Common situations: Migrating code that previously passed only `read_options={"use_columns": [...]}` and then adding the newer top-level `columns=` argument; copy-pasting examples that mix old and new APIs.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

    columns: Sequence[int] | Sequence[str] | None,
    infer_schema_length: int | None,
    has_header: bool,
) -> dict[str, Any]:
    """Normalise top-level parameters to engine-specific 'read_options' dict."""
    read_options = (read_options or {}).copy()

    if engine == "calamine":
        if ("use_columns" in read_options) and columns:
            msg = 'cannot specify both `columns` and `read_options["use_columns"]`'
            raise ParameterCollisionError(msg)
        elif read_options.get("header_row") is not None and has_header is False:
            msg = 'the values of `has_header` and `read_options["header_row"]` are not compatible'
            raise ParameterCollisionError(msg)
        elif ("schema_sample_rows" in read_options) and (
            infer_schema_length != N_INFER_DEFAULT
        ):
            msg = 'cannot specify both `infer_schema_length` and `read_options["schema_sample_rows"]`'
            raise ParameterCollisionError(msg)

        read_options["schema_sample_rows"] = infer_schema_length
        if has_header is False and "header_row" not in read_options:
            read_options["header_row"] = None

    elif engine == "xlsx2csv":
        if ("columns" in read_options) and columns:
            msg = 'cannot specify both `columns` and `read_options["columns"]`'
            raise ParameterCollisionError(msg)
        elif (
            "has_header" in read_options
            and read_options["has_header"] is not has_header
        ):
            msg = 'the values of `has_header` and `read_options["has_header"]` are not compatible'
            raise ParameterCollisionError(msg)
        elif ("infer_schema_length" in read_options) and (
            infer_schema_length != N_INFER_DEFAULT
        ):

View on GitHub (pinned to fe841f959e)