pola-rs/polars · error · ParameterCollisionError

cannot specify both `infer_schema_length` and `read_options[

Error message

cannot specify both `infer_schema_length` and `read_options["schema_sample_rows"]`

What it means

polars.exceptions.ParameterCollisionError raised while normalizing read_excel options for the calamine engine: the top-level infer_schema_length (any value other than the default N_INFER_DEFAULT) collides with read_options['schema_sample_rows']. Both control how many rows calamine samples to infer dtypes, so polars refuses the ambiguous pair during option normalization.

Source

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

    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 df599052da)

Solutions

1. Use the top-level parameter: pl.read_excel(..., infer_schema_length=500) and remove 'schema_sample_rows' from read_options.
2. Or keep it engine-level: read_options={'schema_sample_rows': 500} with infer_schema_length left at its default.
3. Note the default value is allowed through — set infer_schema_length=None explicitly in wrappers only when you also clear schema_sample_rows.

Example fix

# before
pl.read_excel('f.xlsx', infer_schema_length=500, read_options={'schema_sample_rows': 1000})

# after
pl.read_excel('f.xlsx', infer_schema_length=1000)

ro = dict(read_options or {})
if infer_schema_length is not None and 'schema_sample_rows' in ro:
    ro.pop('schema_sample_rows')  # keep the top-level parameter
pl.read_excel(path, infer_schema_length=infer_schema_length, read_options=ro)

try:
    pl.read_excel(path, infer_schema_length=n, read_options=read_options)
except pl.exceptions.ParameterCollisionError as e:
    if 'schema_sample_rows' in str(e):
        ro = {k: v for k, v in (read_options or {}).items() if k != 'schema_sample_rows'}
        pl.read_excel(path, infer_schema_length=n, read_options=ro)
    else:
        raise

When it happens

Trigger: pl.read_excel('f.xlsx', engine='calamine', infer_schema_length=500, read_options={'schema_sample_rows': 500}). Any non-default infer_schema_length together with 'schema_sample_rows' present in read_options.

Common situations: Porting python-calamine code that used schema_sample_rows while also tuning polars' infer_schema_length; shared read_options dicts reused across engines where xlsx2csv/calamine options accumulate.

Related errors

• cannot specify both `columns` and `read_options["use_columns
• the values of `has_header` and `read_options["header_row"]`
• no workbook found at path {src!r}
• no data found in the given workbook(s) and sheet(s)
• no matching sheets found when `sheet_{param}` is {value!r}

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