pola-rs/polars · error · ValueError

{arg_name}="{arg}" should be a single byte character or empt

Error message

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

What it means

_check_arg_is_1byte (py-polars/src/polars/io/csv/_utils.py:18-26) validates single-character CSV arguments in read_csv/read_csv_schema. With can_be_empty=True - used only for quote_char - the UTF-8 encoding of the value may be at most one byte; the empty string '' is allowed (meaning no quote character). Multi-byte characters or multi-character strings raise ValueError naming the argument and its actual byte length.

Source

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

if TYPE_CHECKING:
    from collections.abc import Sequence

    from polars import DataFrame


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

Replace the character with its single-byte ASCII equivalent ('\u201c' -> '"', '\uff5c' -> '|')
Pass quote_char=None to disable quoting if no quoting is present in the file
Normalize configs to ASCII before passing them to read_csv

Example fix

# before
df = pl.read_csv("f.csv", quote_char="\u201c")
# after
df = pl.read_csv("f.csv", quote_char="\"" )

Defensive patterns

Strategy: validation

Validate before calling

def check_one_byte(arg_name: str, value: str | None, allow_empty: bool = True) -> None:
    if value is None:
        return
    n = len(value.encode("utf-8"))
    if (allow_empty and n > 1) or (not allow_empty and n != 1):
        raise ValueError(f"{arg_name}={value!r} is {n} bytes; use a single-byte ASCII character")

Try / catch

try:
    df = pl.read_csv(path, quote_char=qc)
except ValueError as e:
    if "single byte" in str(e):
        df = pl.read_csv(path, quote_char='"')
    else:
        raise

Prevention

Normalize CSV options to ASCII in config loaders (unicodedata.normalize('NFKC', ...) helps for smart quotes)
Never copy quote/delimiter characters directly from spreadsheet apps
Add a lint rule for CSV option values: len(v.encode('utf-8')) <= 1

When it happens

Trigger: pl.read_csv(f, quote_char='\u201c') (typographic quote, 3 UTF-8 bytes); quote_char='||'; any non-ASCII quote copied from Excel/smart-editors. separator='\t' is fine (1 byte).

Common situations: Excel-exported CSVs quoted with curly quotes; editors auto-replacing ASCII quotes with smart quotes; configs that copy the visual delimiter character from a spreadsheet.

Related errors

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