Textualize/textual · error · StyleValueError

{self.name} must be one of {friendly_list(self._valid_values

Error message

{self.name} must be one of {friendly_list(self._valid_values)} (received {value!r})

What it means

Thrown by the StringEnumProperty descriptor when a style rule that only accepts a fixed set of string keywords receives a value outside that set (e.g. `dock`, `display`, `overflow`, `text-align`). The message lists the valid keywords and echoes the offending value so the mistake is obvious. It is a subclass of StyleValueError raised during `styles.<rule> = value` assignment or CSS parsing.

Source

Thrown at src/textual/css/_style_properties.py:859

        """
        _rich_traceback_omit = True
        if value is None:
            if obj.clear_rule(self.name):
                self._before_refresh(obj, value)
                obj.refresh(
                    layout=self._layout,
                    children=self._refresh_children,
                    parent=self._refresh_parent,
                )

                if self._display:
                    node = obj.node
                    if node is not None and node.parent:
                        node._nodes.updated()

        else:
            if value not in self._valid_values:
                raise StyleValueError(
                    f"{self.name} must be one of {friendly_list(self._valid_values)} (received {value!r})",
                    help_text=string_enum_help_text(
                        self.name,
                        valid_values=list(self._valid_values),
                        context="inline",
                    ),
                )
            if obj.set_rule(self.name, value):
                if self._display and obj.node is not None:
                    node = obj.node
                    if node.parent:
                        node._nodes.updated()

                self._before_refresh(obj, value)
                obj.refresh(
                    layout=self._layout,
                    children=self._refresh_children,
                    parent=self._refresh_parent,

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Check the message's friendly_list of valid values and use one of those exact keywords
2. Look up the property in the Textual CSS reference for the full keyword set (e.g. display accepts block, grid, etc.)
3. For layout intents not covered, restructure with containers/grid instead of an unsupported keyword

Example fix

# before
widget.styles.dock = "middle"  # StyleValueError
# after
widget.styles.dock = "top"

valid = {"top","right","bottom","left"}
if value in valid:
    widget.styles.dock = value

When it happens

Trigger: Assigning an invalid keyword to a string-enum style property: `styles.dock = "middle"` (valid: top/right/bottom/left), `styles.display = "inline"`, `styles.overflow = "visible"`, or the same values in a stylesheet rule like `dock: center;`.

Common situations: Typos in CSS TCSS files, copy-pasting web CSS values (e.g. `display: inline-block`, `overflow: visible`) that don't exist in Textual, or assuming a web-CSS keyword applies. Also happens after upgrading Textual when supported keywords change.

Related errors

• {self.name} must be a str
• unknown word {word!r} in style flags
• Expected a str, Path or list[str | Path] for the CSS_PATH.
• invalid percentage value '{token}'
• Invalid color value {color}

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/41a3c5faac9d4e25. Report an issue: GitHub.