pola-rs/polars · error · ValueError

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

Error message

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

What it means

The strict branch of _check_arg_is_1byte (py-polars/src/polars/io/csv/_utils.py:27-34), used for separator and eol_char (can_be_empty=False), requires the value to be exactly one UTF-8 byte: neither the empty string nor multi-byte or multi-character values are accepted. The CSV parser delimits on single bytes, so multi-char delimiters like '\r\n' or '::' are not representable.

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 df599052da)

Solutions

Use the single-byte equivalent: eol_char='\n' (polars handles CRLF files with the default), separator='|' not '\uff5c'
For multi-char delimited files, pre-split lines in Python or transform the file before read_csv
For genuinely non-ASCII single characters, transcode the file or replace the delimiter during preprocessing

Example fix

# before
df = pl.read_csv("f.csv", eol_char="\r\n")
# after
df = pl.read_csv("f.csv", eol_char="\n")

Defensive patterns

Strategy: validation

Validate before calling

def check_strict_one_byte(arg_name: str, value: str) -> None:
    n = len(value.encode("utf-8"))
    if n != 1:
        raise ValueError(
            f"{arg_name}={value!r} must be exactly 1 byte; "
            "multi-char delimiters need preprocessing"
        )

Try / catch

try:
    df = pl.read_csv(path, eol_char=eol)
except ValueError as e:
    if "single byte" in str(e) and eol == "\r\n":
        df = pl.read_csv(path, eol_char="\n")
    else:
        raise

Prevention

Do not pass '\r\n' as eol_char; the default '\n' handles CRLF files
Preprocess multi-character delimiters ('::', '||') before read_csv
Validate separator/eol_char byte length in config validation

When it happens

Trigger: pl.read_csv(f, eol_char='\r\n') (2 bytes - classic CRLF attempt); separator='::'; separator='\u2016' (double vertical line, 3 bytes); separator='' (empty not allowed here, unlike quote_char).

Common situations: Windows line-ending files where users pass eol_char='\r\n'; logical multi-character delimiters from log formats; localized Unicode separators.

Related errors

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