{"record":{"id":"824fb502a30763cd","repo":"pola-rs/polars","slug":"cannot-specify-both-infer-schema-length-and-rea","errorCode":null,"errorMessage":"cannot specify both `infer_schema_length` and `read_options[\"schema_sample_rows\"]`","messagePattern":"cannot specify both `infer_schema_length` and `read_options\\[\"schema_sample_rows\"\\]`","errorType":"validation","errorClass":"ParameterCollisionError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":748,"sourceCode":"\ndef _get_read_options(\n    read_options: dict[str, Any] | None,\n    *,\n    engine: ExcelSpreadsheetEngine,\n    columns: Sequence[int] | Sequence[str] | None,\n    infer_schema_length: int | None,\n    has_header: bool,\n) -> dict[str, Any]:\n    \"\"\"Normalise top-level parameters to engine-specific 'read_options' dict.\"\"\"\n    read_options = (read_options or {}).copy()\n\n    if engine == \"calamine\":\n        if (\"use_columns\" in read_options) and columns:\n            msg = 'cannot specify both `columns` and `read_options[\"use_columns\"]`'\n            raise ParameterCollisionError(msg)\n        elif read_options.get(\"header_row\") is not None and has_header is False:\n            msg = 'the values of `has_header` and `read_options[\"header_row\"]` are not compatible'\n            raise ParameterCollisionError(msg)\n        elif (\"schema_sample_rows\" in read_options) and (\n            infer_schema_length != N_INFER_DEFAULT\n        ):\n            msg = 'cannot specify both `infer_schema_length` and `read_options[\"schema_sample_rows\"]`'\n            raise ParameterCollisionError(msg)\n\n        read_options[\"schema_sample_rows\"] = infer_schema_length\n        if has_header is False and \"header_row\" not in read_options:\n            read_options[\"header_row\"] = None\n\n    elif engine == \"xlsx2csv\":\n        if (\"columns\" in read_options) and columns:\n            msg = 'cannot specify both `columns` and `read_options[\"columns\"]`'\n            raise ParameterCollisionError(msg)\n        elif (\n            \"has_header\" in read_options\n            and read_options[\"has_header\"] is not has_header\n        ):","sourceCodeStart":730,"sourceCodeEnd":766,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/spreadsheet/functions.py#L730-L766","documentation":"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.","triggerScenarios":"pl.read_excel(src, engine='calamine', infer_schema_length=1000, read_options={'schema_sample_rows': 500}).","commonSituations":"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.","solutions":["Keep only one: either pass infer_schema_length at top level, or schema_sample_rows inside read_options, not both.","Set infer_schema_length back to default if you intend to control it solely via read_options.","Search call sites for both parameters and centralize the choice."],"exampleFix":"// before\npl.read_excel('wb.xlsx', infer_schema_length=1000, read_options={'schema_sample_rows': 500})\n// after\npl.read_excel('wb.xlsx', infer_schema_length=1000)","handlingStrategy":"validation","validationCode":"if infer_schema_length is not None and infer_schema_length != 100 and (read_options or {}).get('schema_sample_rows') is not None:\n    raise ValueError('pass only one of infer_schema_length / read_options[\"schema_sample_rows\"]')","typeGuard":null,"tryCatchPattern":"from polars.exceptions import ParameterCollisionError\ntry:\n    df = pl.read_excel(src, infer_schema_length=n, read_options={'schema_sample_rows': m})\nexcept ParameterCollisionError:\n    df = pl.read_excel(src, infer_schema_length=n)","preventionTips":["Choose one sampling knob per codebase and standardize it","Grep call sites for both parameters when upgrading engine options"],"tags":["polars","excel","parameter-collision","schema-inference"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}