pola-rs/polars · error · ValueError

number of characters must be > 0

Error message

number of characters must be > 0

What it means

`pl.Config.set_fmt_str_lengths(n)` sets how many characters of string values are shown when printing. A non-None value must be > 0 because a truncation length of 0 or negative is meaningless; 0 does NOT mean 'unlimited'. None removes the POLARS_FMT_STR_LEN env var and resets the limit.

Source

Thrown at py-polars/src/polars/config.py:883

        └─────────────────────────────────┴─────┘
        >>> with pl.Config(fmt_str_lengths=50):
        ...     print(df)
        shape: (2, 1)
        ┌──────────────────────────────────────────────────┐
        │ txt                                              │
        │ ---                                              │
        │ str                                              │
        ╞══════════════════════════════════════════════════╡
        │ Play it, Sam. Play 'As Time Goes By'.            │
        │ This is the beginning of a beautiful friendship. │
        └──────────────────────────────────────────────────┘
        """
        if n is None:
            os.environ.pop("POLARS_FMT_STR_LEN", None)
        else:
            if n <= 0:
                msg = "number of characters must be > 0"
                raise ValueError(msg)

            os.environ["POLARS_FMT_STR_LEN"] = str(n)
        plr.config_reload_env_var("POLARS_FMT_STR_LEN")
        return cls

    @classmethod
    def set_fmt_table_cell_list_len(cls, n: int | None) -> type[Config]:
        """
        Set the number of elements to display for List values.

        Empty lists will always print "[]". Negative values will result in all values
        being printed. A value of 0 will always "[…]" for lists with contents. A value
        of 1 will print only the final item in the list.

        Parameters
        ----------
        n : int
            Number of values to display.

View on GitHub (pinned to 68506541d2)

Solutions

1. To remove the limit: `pl.Config.set_fmt_str_lengths(None)`.
2. To effectively show everything: pass a large value such as `pl.Config.set_fmt_str_lengths(10_000)`.
3. Guard computed values: `max(1, n)` before passing.

Example fix

# before
pl.Config.set_fmt_str_lengths(0)  # ValueError: number of characters must be > 0

# after
pl.Config.set_fmt_str_lengths(None)  # no truncation limit

def set_str_lengths(n: int | None) -> None:
    if n is not None and n <= 0:
        raise ValueError("use None to remove the string-length limit, not 0")
    pl.Config.set_fmt_str_lengths(n)

When it happens

Trigger: `pl.Config.set_fmt_str_lengths(0)` (hoping to disable truncation) or a negative value; passing a computed length that ended up <= 0.

Common situations: Users pass 0 expecting to show full strings; the correct way to remove the limit is None (or a very large value).

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

• `separator` must be a single character; found {separator!r}
• invalid alignment: {format!r}
• invalid table format name: {format!r} Expected one of: {', '
• limit should be positive
• invalid engine

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