Textualize/textual · error · StylesheetParseError

StylesheetErrors(css_rules) (renderable summarizing CSS rule

Error message

StylesheetErrors(css_rules) (renderable summarizing CSS rule errors)

What it means

Stylesheet.parse raises StylesheetParseError when any parsed CSS rule carries errors; the exception carries a StylesheetErrors renderable that summarizes each failing rule. Note: the raised object wraps the renderable, so str(exception) is not human-readable — print the exception's args or render it.

Source

Thrown at src/textual/css/stylesheet.py:403

            scope,
        ) in self.source.items():
            if css in self._invalid_css:
                continue
            try:
                css_rules = self._parse_rules(
                    css,
                    read_from=read_from,
                    is_default_rules=is_default_rules,
                    tie_breaker=tie_breaker,
                    scope=scope,
                )
            except Exception:
                self._invalid_css.add(css)
                raise
            if any(rule.errors for rule in css_rules):
                error_renderable = StylesheetErrors(css_rules)
                self._invalid_css.add(css)
                raise StylesheetParseError(error_renderable)
            add_rules(css_rules)
        self._rules = rules
        self._require_parse = False
        self._rules_map = None

    def reparse(self) -> None:
        """Re-parse source, applying new variables.

        Raises:
            StylesheetError: If the CSS could not be read.
            StylesheetParseError: If the CSS is invalid.
        """
        # Do this in a fresh Stylesheet so if there are errors we don't break self.
        stylesheet = Stylesheet(variables=self._variables)
        for read_from, (css, is_defaults, tie_breaker, scope) in self.source.items():
            stylesheet.add_source(
                css,
                read_from=read_from,

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Inspect the StylesheetErrors renderable (e.g. print(exc.args[0]) or use Console to render it) to see line numbers and messages
2. Fix or remove the listed rules
3. Lint your TCSS in CI by calling Stylesheet.parse on app CSS in a test

Example fix

# before
raise err  # opaque
# after
try:
    stylesheet.parse()
except StylesheetParseError as e:
    from rich.console import Console
    Console().print(e.args[0])

from textual.css.stylesheet import StylesheetParseError
# in a test:
ss = Stylesheet(); ss.read(path)
try:
    ss.parse()
except StylesheetParseError as e:
    raise AssertionError(f"{path} has CSS errors") from e

from textual.css.stylesheet import StylesheetParseError
from rich.console import Console
try:
    stylesheet.parse()
except StylesheetParseError as e:
    Console().print(e.args[0])  # renderable summary with line numbers

When it happens

Trigger: A stylesheet containing at least one invalid declaration (bad property value, unknown property, malformed selector) after add_rules; parse() aggregates per-rule errors and raises once.

Common situations: Typos or unsupported properties in TCSS, copied CSS from web that Textual doesn't support, or Textual version upgrades that renamed properties.

Related errors

• failed to parse css; {error}
• DeclarationError(name, token, message)
• {token!r} is not a valid scalar
• unable to read CSS file {filename!r}
• Expected a str, Path or list[str | Path] for the CSS_PATH.

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