{"record":{"id":"363bfb542fa36c9c","repo":"pola-rs/polars","slug":"cannot-set-both-with-column-names-and-new-colum","errorCode":null,"errorMessage":"cannot set both `with_column_names` and `new_columns`; mutually exclusive","messagePattern":"cannot set both `with_column_names` and `new_columns`; mutually exclusive","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/csv/functions.py","lineNumber":852,"sourceCode":"    │ u16 ┆ str  │\n    ╞═════╪══════╡\n    │ 1   ┆ is   │\n    │ 2   ┆ hard │\n    │ 3   ┆ to   │\n    │ 4   ┆ read │\n    └─────┴──────┘\n    \"\"\"\n    if schema_overrides is not None and not isinstance(\n        schema_overrides, (dict, Sequence)\n    ):\n        msg = \"`schema_overrides` should be of type list or dict\"\n        raise TypeError(msg)\n\n    if new_columns is not None and with_column_names is not None:\n        msg = (\n            \"cannot set both `with_column_names` and `new_columns`; mutually exclusive\"\n        )\n        raise ValueError(msg)\n\n    _check_arg_is_1byte(\"separator\", separator, can_be_empty=False)\n    _check_arg_is_1byte(\"quote_char\", quote_char, can_be_empty=True)\n\n    if raise_if_empty is None:\n        raise_if_empty = schema is None or has_header\n\n    if isinstance(source, (str, Path)):\n        source = normalize_filepath(source, check_not_directory=False)\n    elif is_path_or_str_sequence(source, allow_str=False):\n        source = [\n            normalize_filepath(source, check_not_directory=False) for source in source\n        ]\n\n    if not infer_schema:\n        infer_schema_length = 0\n\n    if extra_columns is not None:","sourceCodeStart":834,"sourceCodeEnd":870,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/csv/functions.py#L834-L870","documentation":"`scan_csv` offers two ways to rename all columns: the older `with_column_names` and the newer `new_columns`. They are mutually exclusive; supplying both is ambiguous, so polars raises this ValueError before building the scan plan.","triggerScenarios":"`pl.scan_csv(..., with_column_names=[...], new_columns=[...])` — usually after a partial migration from the deprecated `with_column_names` to `new_columns`, or when kwargs are merged from multiple sources (e.g. config + code) and both end up set.","commonSituations":"Refactoring code where the old parameter was left behind; wrapper functions that forward both; copied example code combining two API generations.","solutions":["Remove `with_column_names` and keep only `new_columns` (the current API).","If a wrapper merges dicts of options, filter out the deprecated key before forwarding.","Keep only one of the two lists and verify the column count matches the file."],"exampleFix":"// before\npl.scan_csv(\"f.csv\", with_column_names=[\"a\"], new_columns=[\"a\", \"b\"])\n# after\npl.scan_csv(\"f.csv\", new_columns=[\"a\", \"b\"])","handlingStrategy":"validation","validationCode":"if new_columns is not None and with_column_names is not None:\n    with_column_names = None  # prefer new_columns","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Standardize on `new_columns`; ban `with_column_names` in your codebase lint.","When merging option dicts (config + code), drop deprecated keys.","Search for the old parameter name during polars upgrades."],"tags":["python","csv","lazy","conflicting-options"],"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"}