Textualize/rich · error · ValueError

invalid value for align, expected "left", "center", or "righ

Error message

invalid value for align, expected "left", "center", or "right" (not {align!r})

What it means

Align.__init__ validates its align argument against the allowed set ("left", "center", "right") and raises ValueError for anything else. Rich uses these literal strings (AlignMethod) instead of an enum, so no casing variants or synonyms (e.g. "Left", "centre", "justify") are accepted. The check happens eagerly at construction time, before any rendering occurs.

Source

Thrown at rich/align.py:59

            p = Panel("Hello, [b]World[/b]!", style="on green", width=20)

            # Renders the panel centered in the terminal
            console.print(Align(p, align="center"))
    """

    def __init__(
        self,
        renderable: "RenderableType",
        align: AlignMethod = "left",
        style: Optional[StyleType] = None,
        *,
        vertical: Optional[VerticalAlignMethod] = None,
        pad: bool = True,
        width: Optional[int] = None,
        height: Optional[int] = None,
    ) -> None:
        if align not in ("left", "center", "right"):
            raise ValueError(
                f'invalid value for align, expected "left", "center", or "right" (not {align!r})'
            )
        if vertical is not None and vertical not in ("top", "middle", "bottom"):
            raise ValueError(
                f'invalid value for vertical, expected "top", "middle", or "bottom" (not {vertical!r})'
            )
        self.renderable = renderable
        self.align = align
        self.style = style
        self.vertical = vertical
        self.pad = pad
        self.width = width
        self.height = height

    def __repr__(self) -> str:
        return f"Align({self.renderable!r}, {self.align!r})"

    @classmethod

View on GitHub (pinned to 9d8f9a372c)

Solutions

Correct the value to exactly one of the lowercase strings "left", "center", or "right"
If the value comes from user config, normalize it before passing: strip whitespace and lower() it, then check membership
Validate/normalize at the config boundary so the error surfaces at input parsing, not during rendering

Example fix

// before (Python)
Align(table, align="Centre")  # ValueError
// after
_ALIGN = {"left", "center", "right"}
align = str(cfg["align"]).strip().lower()
if align not in _ALIGN:
    raise ValueError(f"config 'align' must be one of {sorted(_ALIGN)}, got {cfg['align']!r}")
Align(table, align=align)

Defensive patterns

Strategy: type-guard

Validate before calling

align = str(value).strip().lower()
if align not in ("left", "center", "right"):
    raise ValueError(f"align must be left/center/right, got {value!r}")
render = Align(panel, align=align)

Type guard

from typing import Literal, TypeGuard

AlignMethod = Literal["left", "center", "right"]

def is_align_method(v: object) -> TypeGuard[AlignMethod]:
    return v in ("left", "center", "right")

Prevention

Normalize external align values with strip().lower() before constructing Align
Keep a single Literal type alias for AlignMethod and use it in your function signatures so type checkers catch bad values
Validate config values once at load time instead of during rendering

When it happens

Trigger: Calling Align(renderable, align="centre"), Align(renderable, "middle"), or passing a user-supplied config value (e.g. align=cfg['align'] from YAML/CLI) that is misspelled or capitalized differently. Also passing an enum member or a non-string such as None or an int.

Common situations: Config files or CLI flags with British spelling "centre"; capitalization from user input ("Center"); passing None expecting a default; dynamic alignment values from a data schema that uses "justify" or "start"/"end".

Related errors

AI-assisted analysis of Textualize/rich@9d8f9a372c (2026-08-15). Data as JSON: /api/errors/033974ed09782f1f. Report an issue: GitHub.