pola-rs/polars · error · ValueError

specified column names do not start with 'column_', but…

Error message

specified column names do not start with 'column_', but autogenerated header names were requested

What it means

When `read_csv` is called with `has_header=False`, polars auto-generates column names like `column_1`, `column_2`, ... If the caller supplies explicit `schema`/column names that don't follow the `column_` prefix pattern in that mode, polars raises this ValueError because it cannot reconcile user-specified names with the requested autogeneration of header names.

Solutions

Pass your custom names via the parameter designed for it (`new_columns`) instead of `schema` with `has_header=False`.
Alternatively set `has_header=True` if the file actually has a header row and provide names normally.
Or rename your provided names to the `column_N` pattern to match autogenerated names.
Check polars docs for the installed version, as the interplay of `schema`, `has_header`, and `new_columns` has changed across releases.

Example fix

// before
pl.read_csv("f.csv", has_header=False, schema=["a", "b"])
# after
pl.read_csv("f.csv", has_header=False, new_columns=["a", "b"])

Defensive patterns

Strategy: validation

Validate before calling

if has_header is False and schema is not None:
    if not all(c.startswith("column_") for c in schema):
        # switch to new_columns instead
        new_columns = schema
        schema = None

Prevention

Use `new_columns` for renaming headerless CSVs, not `schema`.
Decide explicitly whether the file has a header before choosing schema parameters.
Check the polars version's docs when mixing `schema`/`has_header`/`new_columns`.

When it happens

Trigger: Calling `pl.read_csv(..., has_header=False, schema=["a","b"])` (or new_columns-style name list) where at least one provided name does not start with the literal string `column_`.

Common situations: Reading headerless files while trying to give custom names via `schema` instead of `new_columns`; mixing up which parameter assigns names for headerless CSVs; upgrading polars where the naming convention check became stricter.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

    del columns
    row_index = parse_row_index_args(row_index_name, row_index_offset)
    del row_index_name
    del row_index_offset

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

    storage_options = storage_options or {}

    if column_names and not has_header:
        for column in column_names:
            if not column.startswith("column_"):
                msg = (
                    "specified column names do not start with 'column_',"
                    " but autogenerated header names were requested"
                )
                raise ValueError(msg)

    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 raise_if_empty is None:
        raise_if_empty = schema is None or has_header

    if (
        use_pyarrow
        and schema_overrides is None
        and n_rows is None
        and not low_memory
        and null_values is None
        and with_column_names is None
        and credential_provider == "auto"

View on GitHub (pinned to fe841f959e)