pola-rs/polars · error · ParameterCollisionError

cannot specify both `infer_schema_length` and…

Error message

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

What it means

For the calamine engine, infer_schema_length (top-level) and read_options['schema_sample_rows'] control the same setting. ParameterCollisionError is raised when both are given, since the library cannot decide which sampling length to honor.

Solutions

  1. Keep only one: either pass infer_schema_length at top level, or schema_sample_rows inside read_options, not both.
  2. Set infer_schema_length back to default if you intend to control it solely via read_options.
  3. Search call sites for both parameters and centralize the choice.

Example fix

// before
pl.read_excel('wb.xlsx', infer_schema_length=1000, read_options={'schema_sample_rows': 500})
// after
pl.read_excel('wb.xlsx', infer_schema_length=1000)
Defensive patterns

Strategy: validation

Validate before calling

if infer_schema_length is not None and infer_schema_length != 100 and (read_options or {}).get('schema_sample_rows') is not None:
    raise ValueError('pass only one of infer_schema_length / read_options["schema_sample_rows"]')

Try / catch

from polars.exceptions import ParameterCollisionError
try:
    df = pl.read_excel(src, infer_schema_length=n, read_options={'schema_sample_rows': m})
except ParameterCollisionError:
    df = pl.read_excel(src, infer_schema_length=n)

Prevention

When it happens

Trigger: pl.read_excel(src, engine='calamine', infer_schema_length=1000, read_options={'schema_sample_rows': 500}).

Common situations: Users tune sampling via read_options while an existing codebase call already passes infer_schema_length; copy-pasted config across engines that use different option names.

Related errors

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

Appendix: source

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

def _get_read_options(
    read_options: dict[str, Any] | None,
    *,
    engine: ExcelSpreadsheetEngine,
    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
        ):

View on GitHub (pinned to fe841f959e)