{"record":{"id":"f1b5ffe8290fec7b","repo":"pola-rs/polars","slug":"the-values-of-has-header-and-read-options-has","errorCode":null,"errorMessage":"the values of `has_header` and `read_options[\"has_header\"]` are not compatible","messagePattern":"the values of `has_header` and `read_options\\[\"has_header\"\\]` are not compatible","errorType":"validation","errorClass":"ParameterCollisionError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":762,"sourceCode":"            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        ):\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","sourceCodeStart":744,"sourceCodeEnd":780,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/spreadsheet/functions.py#L744-L780","documentation":"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.","triggerScenarios":"Calling `pl.read_excel(..., engine='xlsx2csv', has_header=True, read_options={'has_header': False})` or any combination where both are specified with differing values.","commonSituations":"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.","solutions":["Remove `has_header` from `read_options` and rely on the top-level `has_header=` parameter","Or drop the top-level argument and set it only in `read_options`","Ensure both, if truly required to coexist, are the identical value"],"exampleFix":"// before\npl.read_excel(f, engine='xlsx2csv', has_header=True, read_options={'has_header': False})\n// after\npl.read_excel(f, engine='xlsx2csv', has_header=True)","handlingStrategy":"validation","validationCode":"assert not ('has_header' in read_options and read_options['has_header'] != has_header), 'has_header conflict'","typeGuard":null,"tryCatchPattern":"from polars.exceptions import ParameterCollisionError\ntry:\n    pl.read_excel(f, engine='xlsx2csv', has_header=hh, read_options=ro)\nexcept ParameterCollisionError:\n    ro.pop('has_header', None)\n    df = pl.read_excel(f, engine='xlsx2csv', has_header=hh, read_options=ro)","preventionTips":["Prefer the top-level has_header parameter","Sanitize read_options dicts before passing them","Unit-test config assembly code for duplicate keys"],"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"}