pola-rs/polars · error · ValueError

invalid alignment: {format!r}

Error message

invalid alignment: {format!r}

What it means

`pl.Config.set_tbl_cell_alignment(format)` upper-cases the input and requires one of LEFT, CENTER, or RIGHT (None clears the setting). Any other string raises ValueError before POLARS_FMT_TABLE_CELL_ALIGNMENT is written.

Source

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

        ┌────────────┬────────────┐
        │ column_abc ┆ column_xyz │
        │        --- ┆        --- │
        │        f64 ┆       bool │
        ╞════════════╪════════════╡
        │        1.0 ┆       true │
        │        2.5 ┆      false │
        │        5.0 ┆       true │
        └────────────┴────────────┘

        Raises
        ------
        ValueError: if alignment string not recognised.
        """
        if format is None:
            os.environ.pop("POLARS_FMT_TABLE_CELL_ALIGNMENT", None)
        elif (format := format.upper()) not in {"LEFT", "CENTER", "RIGHT"}:  # type: ignore[assignment]
            msg = f"invalid alignment: {format!r}"
            raise ValueError(msg)
        else:
            os.environ["POLARS_FMT_TABLE_CELL_ALIGNMENT"] = format
        plr.config_reload_env_var("POLARS_FMT_TABLE_CELL_ALIGNMENT")
        return cls

    @classmethod
    def set_tbl_cell_numeric_alignment(cls, format: Alignment | None) -> type[Config]:
        """
        Set table cell alignment for numeric columns.

        Parameters
        ----------
        format : str
            * "LEFT": left aligned
            * "CENTER": center aligned
            * "RIGHT": right aligned

        Examples

View on GitHub (pinned to 68506541d2)

Solutions

1. Use one of 'LEFT', 'CENTER', 'RIGHT' (any casing — it is upper-cased for you).
2. Pass None to reset to the default alignment.

Example fix

# before
pl.Config.set_tbl_cell_alignment("centre")  # ValueError: invalid alignment

# after
pl.Config.set_tbl_cell_alignment("CENTER")

VALID_ALIGNMENTS = frozenset({"LEFT", "CENTER", "RIGHT"})

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

from typing import Literal

Alignment = Literal["LEFT", "CENTER", "RIGHT"]

def is_alignment(value: str) -> TypeGuard[Alignment]:
    return value.upper() in {"LEFT", "CENTER", "RIGHT"}

When it happens

Trigger: `pl.Config.set_tbl_cell_alignment('centre')` (British spelling), 'middle', 'justify', 'default', or a numeric alignment code.

Common situations: Non-US spelling ('centre'); guessing alignment names; passing an enum value from another library.

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 table format name: {format!r} Expected one of: {', '
• `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/777a96990029ab03. Report an issue: GitHub.