{"record":{"id":"009125c028309ae3","repo":"pola-rs/polars","slug":"cannot-specify-both-infer-schema-length-and-rea-009125","errorCode":null,"errorMessage":"cannot specify both `infer_schema_length` and `read_options[\"infer_schema_length\"]`","messagePattern":"cannot specify both `infer_schema_length` and `read_options\\[\"infer_schema_length\"\\]`","errorType":"validation","errorClass":"ParameterCollisionError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":768,"sourceCode":"            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        ):\n            msg = 'the values of `has_header` and `read_options[\"has_header\"]` are not compatible'\n            raise ParameterCollisionError(msg)\n        elif (\"infer_schema_length\" in read_options) and (\n            infer_schema_length != N_INFER_DEFAULT\n        ):\n            msg = 'cannot specify both `infer_schema_length` and `read_options[\"infer_schema_length\"]`'\n            raise ParameterCollisionError(msg)\n\n        read_options[\"infer_schema_length\"] = infer_schema_length\n        if \"has_header\" not in read_options:\n            read_options[\"has_header\"] = has_header\n    else:\n        read_options[\"infer_schema_length\"] = infer_schema_length\n        read_options[\"has_header\"] = has_header\n\n    return read_options\n\n\ndef _get_sheet_names(\n    sheet_id: int | Sequence[int] | None,","sourceCodeStart":750,"sourceCodeEnd":786,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/spreadsheet/functions.py#L750-L786","documentation":"For the xlsx2csv engine, `read_excel` injects the top-level `infer_schema_length` into `read_options[\"infer_schema_length\"]`. If the caller set `infer_schema_length` inside `read_options` while also passing a non-default top-level `infer_schema_length`, both compete and Polars raises `ParameterCollisionError`.","triggerScenarios":"`pl.read_excel(..., engine='xlsx2csv', infer_schema_length=100, read_options={'infer_schema_length': 0})` — any non-None/non-default top-level value combined with the key in read_options.","commonSituations":"Tuning schema inference in two places after upgrading; spreading a config dict into read_options that already contains infer_schema_length.","solutions":["Remove `infer_schema_length` from `read_options` and use the top-level parameter","Or drop the top-level `infer_schema_length` and configure it only via read_options"],"exampleFix":"// before\npl.read_excel(f, engine='xlsx2csv', infer_schema_length=100, read_options={'infer_schema_length': 0})\n// after\npl.read_excel(f, engine='xlsx2csv', read_options={'infer_schema_length': 0})","handlingStrategy":"validation","validationCode":"assert not ('infer_schema_length' in read_options and infer_schema_length is not None), 'infer_schema_length conflict'","typeGuard":null,"tryCatchPattern":"from polars.exceptions import ParameterCollisionError\ntry:\n    pl.read_excel(f, engine='xlsx2csv', infer_schema_length=n, read_options=ro)\nexcept ParameterCollisionError:\n    ro.pop('infer_schema_length', None)\n    df = pl.read_excel(f, engine='xlsx2csv', infer_schema_length=n, read_options=ro)","preventionTips":["Set schema inference only via the top-level argument","Audit config dicts for engine-native keys","Document which parameters are duplicated in read_options"],"tags":["python","polars","parameter-collision","excel"],"backgroundTag":"conflicting-config-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"}