pola-rs/polars · error · ValueError

=" " should be a single byte character, but is bytes long

Error message

{arg_name}="{arg}" should be a single byte character, but is {arg_byte_length} bytes long

What it means

CSV single-character arguments passed to `read_csv`, `scan_csv`, `write_csv`, or `sink_csv` must encode to exactly one UTF-8 byte. `_check_arg_is_1byte` raises this ValueError when the argument's byte length is not exactly 1 (the non-empty branch). This exists because the Rust CSV reader/writer treats these options as single-byte tokens.

Solutions

Check `len(arg.encode("utf-8")) == 1` before the call and fix the value.
Use a single ASCII character, e.g. `separator=";"`, `quote_char='"'`.
For multi-character delimiters, pre-process the file or read it as a plain text and split manually — polars CSV options only accept one byte.
If you meant the default comma, omit `separator` entirely.

Example fix

// before
pl.read_csv("data.csv", quote_char="”")  # multi-byte smart quote
# after
pl.read_csv("data.csv", quote_char='"')

Defensive patterns

Strategy: validation

Validate before calling

assert len(sep.encode("utf-8")) == 1, f"separator must be 1 byte: {sep!r}"

Prevention

Never pass "" for arguments that don't allow empty (separator, etc.).
Beware non-ASCII characters: check `len(s.encode('utf-8'))`, not `len(s)`.
For multi-char delimiters, preprocess the file rather than forcing a CSV option.

When it happens

Trigger: Passing a separator, quote_char, or similar option that is empty or longer than one byte where an empty string is not allowed — e.g. `separator=""`, `separator="; "`, or a multi-byte character like `separator="§"` in some encodings.

Common situations: Passing an empty string thinking it means 'default'; using strings like "\r\n" or "::" as separators; Unicode characters whose UTF-8 encoding exceeds one byte; locale/keyboard introducing smart quotes as quote_char.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at py-polars/src/polars/io/csv/_utils.py:28

def _check_arg_is_1byte(
    arg_name: str, arg: str | None, *, can_be_empty: bool = False
) -> None:
    if isinstance(arg, str):
        arg_byte_length = len(arg.encode("utf-8"))
        if can_be_empty:
            if arg_byte_length > 1:
                msg = (
                    f'{arg_name}="{arg}" should be a single byte character or empty,'
                    f" but is {arg_byte_length} bytes long"
                )
                raise ValueError(msg)
        elif arg_byte_length != 1:
            msg = (
                f'{arg_name}="{arg}" should be a single byte character, but is'
                f" {arg_byte_length} bytes long"
            )
            raise ValueError(msg)


def _update_columns(df: DataFrame, new_columns: Sequence[str]) -> DataFrame:
    if df.width > len(new_columns):
        cols = df.columns
        for i, name in enumerate(new_columns):
            cols[i] = name
        new_columns = cols
    df.columns = list(new_columns)
    return df

View on GitHub (pinned to fe841f959e)