pola-rs/polars · error · ValueError

cannot set truncate_ragged_lines=False with extra_columns='i

Error message

cannot set truncate_ragged_lines=False with extra_columns='ignore'

What it means

ValueError raised by pl.scan_csv because truncate_ragged_lines=False is logically incompatible with extra_columns='ignore'. Ignoring extra columns means tolerating ragged rows (truncation defaults on in that case), so explicitly forbidding truncation while ignoring extra columns contradicts itself and is rejected.

Source

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

    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:
        msg = "The `extra_columns` parameter of `scan_csv` is considered unstable."
        issue_unstable_warning(msg)
    else:
        extra_columns = "raise"

    if extra_columns == "ignore" and truncate_ragged_lines is False:
        msg = "cannot set truncate_ragged_lines=False with extra_columns='ignore'"
        raise ValueError(msg)

    if truncate_ragged_lines is None:
        truncate_ragged_lines = extra_columns == "ignore"

    if missing_columns is not None:
        msg = "The `missing_columns` parameter of `scan_csv` is considered unstable."
        issue_unstable_warning(msg)

    credential_provider_builder = _init_credential_provider_builder(
        credential_provider, source, storage_options, "scan_csv"
    )
    del credential_provider

    dtype_list: list[tuple[str, PolarsDataType]] | None = None
    dtype_slice: Sequence[PolarsDataType] | None = None
    if schema_overrides is not None:
        if isinstance(schema_overrides, dict):
            dtype_list = []

View on GitHub (pinned to 68506541d2)

Solutions

1. Drop truncate_ragged_lines (let it default to True when extra_columns='ignore')
2. Or use extra_columns='raise'/'insert' with truncate_ragged_lines=False if you want strict truncation semantics
3. Pre-clean the file or use skip_rows/new_columns to normalize widths

Example fix

# before
pl.scan_csv('f.csv', extra_columns='ignore', truncate_ragged_lines=False)
# after
pl.scan_csv('f.csv', extra_columns='ignore')

if extra_columns == 'ignore' and truncate_ragged_lines is False:
    truncate_ragged_lines = None  # let it default to True

When it happens

Trigger: pl.scan_csv('f.csv', extra_columns='ignore', truncate_ragged_lines=False) — files whose rows have more fields than the schema, where the user wants extras dropped but no truncation.

Common situations: Messy CSV exports with inconsistent row widths; migrating from read_csv error-handling combos; defensive parameter sets copied from other scan calls.

Related errors

• list.to_struct() got a str instead of a list. hint: pass ['{
• schema_mode='overwrite' requires mode='overwrite'
• activate 'timezones' feature
• activate one of {{'dtype-date', 'dtype-datetime', dtype-time
• invalid value for POLARS_FORCE_CSV_INFER_READ_SIZE: {x}

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-28). Data as JSON: /api/errors/afb138a1d8391350. Report an issue: GitHub.