{"record":{"id":"21ffc0c8c95b8b4b","repo":"pola-rs/polars","slug":"cannot-specify-columns-in-both-schema-overrides","errorCode":null,"errorMessage":"cannot specify columns in both `schema_overrides` and `read_options['dtypes']`","messagePattern":"cannot specify columns in both `schema_overrides` and `read_options\\['dtypes'\\]`","errorType":"exception","errorClass":"ParameterCollisionError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":934,"sourceCode":"    csv.seek(0)\n\n    if read_options is None:\n        read_options = {}\n\n    date_cols = []\n    if schema_overrides:\n        if csv_dtypes := read_options.get(\"dtypes\", {}):\n            issue_deprecation_warning(\n                \"the `dtypes` parameter for `read_csv` is deprecated. It has been renamed to `schema_overrides`.\",\n                version=\"0.20.31\",\n            )\n\n        csv_schema_overrides = cast(\n            \"SchemaDict\", read_options.get(\"schema_overrides\", csv_dtypes)\n        )\n        if set(csv_schema_overrides).intersection(schema_overrides):\n            msg = \"cannot specify columns in both `schema_overrides` and `read_options['dtypes']`\"\n            raise ParameterCollisionError(msg)\n\n        overrides, schema_overrides = {**csv_schema_overrides, **schema_overrides}, {}\n        for nm, dtype in overrides.items():\n            if dtype != Date:\n                schema_overrides[nm] = dtype\n            else:\n                date_cols.append(nm)\n\n        read_options = read_options.copy()\n        read_options[\"schema_overrides\"] = schema_overrides\n\n    df = _drop_null_data(\n        df=read_csv(\n            csv,\n            separator=separator,\n            **read_options,\n        ),\n        raise_if_empty=raise_if_empty,","sourceCodeStart":916,"sourceCodeEnd":952,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L916-L952","documentation":"Raised by the xlsx2csv path of pl.read_excel (in _csv_buffer_to_frame) as a ParameterCollisionError when the top-level schema_overrides shares at least one column key with dtype overrides smuggled in read_options — either read_options['schema_overrides'] or the deprecated read_options['dtypes'] (which first triggers a deprecation warning dated 0.20.31). Only the key SET intersection matters: disjoint dicts are merged without error. Note ParameterCollisionError subclasses PolarsError, not ValueError.","triggerScenarios":"pl.read_excel(src, engine='xlsx2csv', schema_overrides={'a': pl.Int64}, read_options={'dtypes': {'a': pl.Float64}}) or read_options={'schema_overrides': {'a': pl.Int64}} — any overlap of column names between the two layers raises.","commonSituations":"Copy-pasting read_csv(..., dtypes=...) kwargs into read_options while also using polars' schema_overrides parameter; older tutorials that used read_options['dtypes']; central config dicts that carry csv dtype maps.","solutions":["Consolidate ALL column type overrides into the top-level schema_overrides parameter","Remove 'dtypes' (deprecated) and 'schema_overrides' keys from read_options entirely","Keep read_options for csv-mechanics keys only (separator, skip_rows, truncate_ragged_lines, ...)"],"exampleFix":"# before\npl.read_excel(src, engine='xlsx2csv', schema_overrides={'id': pl.Int64}, read_options={'dtypes': {'id': pl.Float64}})\n\n# after\npl.read_excel(src, engine='xlsx2csv', schema_overrides={'id': pl.Int64})","handlingStrategy":"validation","validationCode":"opts = dict(read_options or {})\ninline_overrides = set(opts.pop('dtypes', {})) | set(opts.pop('schema_overrides', {}))\nif inline_overrides & set(schema_overrides or {}):\n    raise ValueError('same column overridden in both schema_overrides and read_options')\n# merge once, top-level only\nschema_overrides = {**{k: v for k, v in read_options.get('dtypes', {}).items()}, **(schema_overrides or {})}\ndf = pl.read_excel(src, engine='xlsx2csv', schema_overrides=schema_overrides, read_options=opts)","typeGuard":null,"tryCatchPattern":"from polars.exceptions import ParameterCollisionError\ntry:\n    df = pl.read_excel(src, engine='xlsx2csv', schema_overrides=ov, read_options=opts)\nexcept ParameterCollisionError as e:\n    if 'schema_overrides' in str(e):\n        opts.pop('dtypes', None); opts.pop('schema_overrides', None)\n        df = pl.read_excel(src, engine='xlsx2csv', schema_overrides=ov, read_options=opts)\n    else:\n        raise","preventionTips":["Declare one home for dtype overrides (the top-level schema_overrides parameter) and lint read_options for 'dtypes'/'schema_overrides' keys","'dtypes' in read_options is deprecated since 0.20.31 — migrate it away now","Only overlapping column names raise; run a set-intersection assertion in your config loader to fail with a clear message"],"tags":["polars","excel","xlsx2csv","schema-overrides","parameter-collision","deprecated"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}