pola-rs/polars · error · ValueError

cannot set both `with_column_names` and `new_columns`…

Error message

cannot set both `with_column_names` and `new_columns`; mutually exclusive

What it means

`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.

Solutions

1. Remove `with_column_names` and keep only `new_columns` (the current API).
2. If a wrapper merges dicts of options, filter out the deprecated key before forwarding.
3. Keep only one of the two lists and verify the column count matches the file.

Example fix

// before
pl.scan_csv("f.csv", with_column_names=["a"], new_columns=["a", "b"])
# after
pl.scan_csv("f.csv", new_columns=["a", "b"])

if new_columns is not None and with_column_names is not None:
    with_column_names = None  # prefer new_columns

When it happens

Trigger: `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.

Common situations: Refactoring code where the old parameter was left behind; wrapper functions that forward both; copied example code combining two API generations.

Related errors

• cannot set truncate_ragged_lines=False with…
• `schema_overrides` should be of type list or dict, got
• =" " should be a single byte character or empty, but is…
• =" " should be a single byte character, but is bytes long
• can not match overlapping patterns when leftmost == True

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/363bfb542fa36c9c. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/io/csv/functions.py:852

    │ u16 ┆ str  │
    ╞═════╪══════╡
    │ 1   ┆ is   │
    │ 2   ┆ hard │
    │ 3   ┆ to   │
    │ 4   ┆ read │
    └─────┴──────┘
    """
    if schema_overrides is not None and not isinstance(
        schema_overrides, (dict, Sequence)
    ):
        msg = "`schema_overrides` should be of type list or dict"
        raise TypeError(msg)

    if new_columns is not None and with_column_names is not None:
        msg = (
            "cannot set both `with_column_names` and `new_columns`; mutually exclusive"
        )
        raise ValueError(msg)

    _check_arg_is_1byte("separator", separator, can_be_empty=False)
    _check_arg_is_1byte("quote_char", quote_char, can_be_empty=True)

    if raise_if_empty is None:
        raise_if_empty = schema is None or has_header

    if isinstance(source, (str, Path)):
        source = normalize_filepath(source, check_not_directory=False)
    elif is_path_or_str_sequence(source, allow_str=False):
        source = [
            normalize_filepath(source, check_not_directory=False) for source in source
        ]

    if not infer_schema:
        infer_schema_length = 0

    if extra_columns is not None:

View on GitHub (pinned to fe841f959e)