pola-rs/polars · error

invalid table format name

Error message

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

What it means

Config.set_tbl_formatting validates the table style name against the TableFormatNames Literal (via typing.get_args) before storing it in POLARS_FMT_TABLE_FORMATTING. An unrecognized name raises a ValueError listing all valid names. None resets the setting.

Solutions

1. Use a name from the error message's 'Expected one of:' list (e.g. 'ASCII_FULL', 'UTF8_FULL').
2. Pass None to reset formatting to default.
3. Import TableFormatNames and check membership before calling.

Example fix

// before
pl.Config.set_tbl_formatting("fancy_grid")
// after
pl.Config.set_tbl_formatting("UTF8_FULL")

from typing import get_args
from polars.datatypes import TableFormatNames  # or import from its module
valid = get_args(TableFormatNames)
if fmt is not None and fmt.upper() not in valid:
    raise ValueError(f"fmt must be one of {valid}")
pl.Config.set_tbl_formatting(fmt)

def is_valid_table_format(v, valid) -> bool:
    return v is None or (isinstance(v, str) and v.upper() in valid)

try:
    pl.Config.set_tbl_formatting(fmt)
except ValueError as e:
    print(e)  # message lists all valid names
    pl.Config.set_tbl_formatting(None)

When it happens

Trigger: pl.Config.set_tbl_formatting('fancy_grid') or any string not in the valid TableFormatNames set (e.g. 'ASCII_FULL', 'UTF8_FULL', etc.).

Common situations: Copying table style names from the rich library or other DataFrame libs whose style vocabularies differ; guessing a style name instead of reading the error's 'Expected one of:' list.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid alignment
• invalid engine
• {credential_provider}
• engine must be one of
• limit should be positive

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

Appendix: 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 fe841f959e)