pola-rs/polars · error · ParameterCollisionError

the values of `has_header` and `read_options["has_header"]`…

Error message

the values of `has_header` and `read_options["has_header"]` are not compatible

What it means

When using the xlsx2csv engine, `read_excel` compares the top-level `has_header` flag with any `has_header` supplied inside `read_options` using identity (`is not`). If both are given and they are not the same object (e.g. True vs False), it raises `ParameterCollisionError` because the intent is contradictory.

Solutions

  1. Remove `has_header` from `read_options` and rely on the top-level `has_header=` parameter
  2. Or drop the top-level argument and set it only in `read_options`
  3. Ensure both, if truly required to coexist, are the identical value

Example fix

// before
pl.read_excel(f, engine='xlsx2csv', has_header=True, read_options={'has_header': False})
// after
pl.read_excel(f, engine='xlsx2csv', has_header=True)
Defensive patterns

Strategy: validation

Validate before calling

assert not ('has_header' in read_options and read_options['has_header'] != has_header), 'has_header conflict'

Try / catch

from polars.exceptions import ParameterCollisionError
try:
    pl.read_excel(f, engine='xlsx2csv', has_header=hh, read_options=ro)
except ParameterCollisionError:
    ro.pop('has_header', None)
    df = pl.read_excel(f, engine='xlsx2csv', has_header=hh, read_options=ro)

Prevention

When it happens

Trigger: Calling `pl.read_excel(..., engine='xlsx2csv', has_header=True, read_options={'has_header': False})` or any combination where both are specified with differing values.

Common situations: Merging a shared `read_options` dict that already sets `has_header` with an explicit keyword argument; refactoring where the flag was moved into read_options but not removed from the signature.

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/f1b5ffe8290fec7b. Report an issue: GitHub.

Appendix: source

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

            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
        ):
            msg = 'cannot specify both `infer_schema_length` and `read_options["infer_schema_length"]`'
            raise ParameterCollisionError(msg)

        read_options["infer_schema_length"] = infer_schema_length
        if "has_header" not in read_options:
            read_options["has_header"] = has_header
    else:
        read_options["infer_schema_length"] = infer_schema_length
        read_options["has_header"] = has_header

View on GitHub (pinned to fe841f959e)