{"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":1408,"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 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 retries is not None:\n        msg = \"the `retries` parameter was deprecated in 1.37.1; specify 'max_retries' in `storage_options` instead.\"\n        issue_deprecation_warning(msg)\n        storage_options = storage_options or {}","sourceCodeStart":1390,"sourceCodeEnd":1426,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/csv/functions.py#L1390-L1426","documentation":"scan_csv offers two mutually exclusive ways to control header names: with_column_names (a callable that receives the parsed header list and returns a modified one) and new_columns (a fixed list of replacement names). Setting both is ambiguous - which one wins for name-dependent features like schema_overrides? - so polars rejects the combination immediately with this ValueError.","triggerScenarios":"pl.scan_csv('f.csv', with_column_names=lambda cols: [c.lower() for c in cols], new_columns=['a', 'b']); any call where both kwargs are not None.","commonSituations":"Layered utility functions where one layer adds with_column_names normalization and a caller also passes new_columns; copy-paste from two different doc examples into one call.","solutions":["Keep only new_columns if the full target name list is known up front","Keep only with_column_names if names must be derived from the file's header (e.g. lowercasing, stripping whitespace)","For headerless files, prefer new_columns (or a schema) since there is no header for with_column_names to transform"],"exampleFix":"# before\npl.scan_csv('f.csv',\n            with_column_names=lambda cols: [c.lower() for c in cols],\n            new_columns=['a', 'b'])\n\n# after - one mechanism only\npl.scan_csv('f.csv', new_columns=['a', 'b'])\n# or\npl.scan_csv('f.csv', with_column_names=lambda cols: [c.lower() for c in cols])","handlingStrategy":"validation","validationCode":"if new_columns is not None and with_column_names is not None:\n    raise ValueError(\n        'pipeline config sets both new_columns and with_column_names; pick one'\n    )\nlf = pl.scan_csv(path, new_columns=new_columns,\n                  with_column_names=with_column_names)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In layered wrappers, let only one layer own header naming - pass through the other option untouched","Use new_columns for fixed schemas, with_column_names only when names depend on the file's own header","Add a lint/assert in shared loader utilities that the two kwargs are never both set"],"tags":["polars","csv","lazy","column-names","mutually-exclusive","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}