pola-rs/polars · error · ValueError

invalid table format name: {format!r} Expected one of: {', '

Error message

invalid table format name: {format!r}
Expected one of: {', '.join(valid_format_names)}

What it means

`pl.Config.set_tbl_formatting(format)` validates the preset name against `TableFormatNames`, the comfy-table presets polars exposes (ASCII_FULL, ASCII_BORDERS_ONLY, ASCII_CONDENSED, UTF8_FULL, UTF8_NO_BORDERS, etc.). Unknown names raise ValueError, and the message helpfully lists every valid name.

Source

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

        ...     print(df)
        | abc  | mno   | xyz   |
        |------|-------|-------|
        | -2.5 | hello | true  |
        | 5.0  | world | false |

        Raises
        ------
        ValueError: if format string not recognised.
        """
        # note: can see what the different styles look like in the comfy-table tests
        # https://github.com/Nukesor/comfy-table/blob/main/tests/all/presets_test.rs
        if format is None:
            os.environ.pop("POLARS_FMT_TABLE_FORMATTING", None)
        else:
            valid_format_names = get_args(TableFormatNames)
            if (format_upper := format.upper()) not in valid_format_names:
                msg = f"invalid table format name: {format!r}\nExpected one of: {', '.join(valid_format_names)}"
                raise ValueError(msg)
            os.environ["POLARS_FMT_TABLE_FORMATTING"] = format_upper
        plr.config_reload_env_var("POLARS_FMT_TABLE_FORMATTING")

        if rounded_corners is None:
            os.environ.pop("POLARS_FMT_TABLE_ROUNDED_CORNERS", None)
        else:
            os.environ["POLARS_FMT_TABLE_ROUNDED_CORNERS"] = str(int(rounded_corners))
        plr.config_reload_env_var("POLARS_FMT_TABLE_ROUNDED_CORNERS")

        return cls

    @classmethod
    def set_tbl_hide_column_data_types(cls, active: bool | None = True) -> type[Config]:
        """
        Hide table column data types (i64, f64, str etc.).

        Examples
        --------

View on GitHub (pinned to 68506541d2)

Solutions

1. Read the valid names straight from the error message — it prints the full list.
2. In code: `import typing; from polars._typing import TableFormatNames; typing.get_args(TableFormatNames)`.
3. Check the polars changelog if a name that used to work now fails.

Example fix

# before
pl.Config.set_tbl_formatting("markdown")  # ValueError: invalid table format name

# after
pl.Config.set_tbl_formatting("ASCII_MARKDOWN")

import typing
from polars._typing import TableFormatNames

VALID_FORMATS = frozenset(typing.get_args(TableFormatNames))

def set_table_format(fmt: str | None) -> None:
    if fmt is not None and fmt.upper() not in VALID_FORMATS:
        raise ValueError(f"format must be one of {sorted(VALID_FORMATS)}, got {fmt!r}")
    pl.Config.set_tbl_formatting(fmt)

import typing
from polars._typing import TableFormatNames

def is_table_format_name(value: str) -> bool:
    return value.upper() in typing.get_args(TableFormatNames)

When it happens

Trigger: `pl.Config.set_tbl_formatting('pretty')`, 'grid', 'markdown', 'psql' (a tabulate name, not a polars preset), or a preset name removed/renamed in another polars version.

Common situations: Guessing format names by analogy with other table libraries (tabulate/prettytable); version drift after upgrading polars; typos in lowercase names (upper-cased for you, so case is not the issue).

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

• invalid alignment: {format!r}
• `separator` must be a single character; found {separator!r}
• number of characters must be > 0
• limit should be positive
• invalid engine

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