Textualize/textual · error · StylesheetError

failed to parse css; {error}

Error message

failed to parse css; {error}

What it means

Stylesheet._parse_rules wraps any unexpected exception raised while parsing CSS rules into StylesheetError('failed to parse css; ...'). TokenError subclasses pass through unchanged; everything else (ValueError, KeyError, TypeError from rule construction) is wrapped here.

Source

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

            return self._parse_cache[cache_key]
        except KeyError:
            pass
        try:
            rules = list(
                parse(
                    scope,
                    css,
                    read_from,
                    variable_tokens=self._variable_tokens,
                    is_default_rules=is_default_rules,
                    tie_breaker=tie_breaker,
                )
            )

        except TokenError:
            raise
        except Exception as error:
            raise StylesheetError(f"failed to parse css; {error}") from None

        self._parse_cache[cache_key] = rules
        return rules

    def read(self, filename: str | PurePath) -> None:
        """Read Textual CSS file.

        Args:
            filename: Filename of CSS.

        Raises:
            StylesheetError: If the CSS could not be read.
            StylesheetParseError: If the CSS is invalid.
        """
        filename = os.path.expanduser(filename)
        try:
            with open(filename, "rt", encoding="utf-8") as css_file:
                css = css_file.read()

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Read the wrapped {error} portion — it names the actual failing value
2. Check the property value against Textual's supported values (easing names, align values, etc.)
3. If upgrading Textual, re-check the CSS reference for changed property syntax

Example fix

/* before */
easing: smooth-in-out;
/* after */
easing: in_out_cubic;

from textual.css.stylesheet import Stylesheet
ss = Stylesheet()
ss.add_source(css, read_from="check.tcss")
try:
    ss.parse()
except Exception:
    raise  # fail fast in CI before shipping CSS

from textual.css.stylesheet import StylesheetError
try:
    stylesheet.parse()
except StylesheetError as e:
    report(f"CSS parse failed: {e}")

When it happens

Trigger: Valid-tokenized CSS that still fails rule building — invalid easing function, bad opacity value, invalid text-align, or any value that passes tokenization but fails validation in Styles construction.

Common situations: Typos in property values that the tokenizer accepts (e.g. 'easing: bounce-quickly', 'opacity: 150%'), or running CSS written for a newer/older Textual version against an incompatible one.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• StylesheetErrors(css_rules) (renderable summarizing CSS rule
• 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/acadaf8c7494e2e9. Report an issue: GitHub.