Textualize/textual · error · DeclarationError

DeclarationError(name, token, message)

Error message

DeclarationError(name, token, message)

What it means

StylesBuilder.error is the central raiser for DeclarationError while building Styles from parsed CSS declarations. Callers (add_declaration, enum/scalar processors, process_display, process_box_sizing) format a message and token; this method attaches the rule name and source token and raises DeclarationError, which surfaces as a stylesheet error with position info.

Source

Thrown at src/textual/css/_styles_builder.py:106

class StylesBuilder:
    """
    The StylesBuilder object takes tokens parsed from the CSS and converts
    to the appropriate internal types.
    """

    def __init__(self) -> None:
        self.styles = Styles()

    def __rich_repr__(self) -> rich.repr.Result:
        yield "styles", self.styles

    def __repr__(self) -> str:
        return "StylesBuilder()"

    def error(self, name: str, token: Token, message: str | HelpText) -> NoReturn:
        raise DeclarationError(name, token, message)

    def add_declaration(self, declaration: Declaration) -> None:
        if not declaration.name:
            return
        rule_name = declaration.name.replace("-", "_")

        if not declaration.tokens:
            self.error(
                rule_name,
                declaration.token,
                f"Missing property value for '{declaration.name}:'",
            )

        process_method = getattr(self, f"process_{rule_name}", None)

        if process_method is None:
            suggested_property_name = self._get_suggested_property_name_for_rule(
                declaration.name

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Read the DeclarationError's name/token/message fields — they identify the exact rule and CSS token; the StylesBuilder.error frame is just plumbing
2. Fix the named declaration in the stylesheet or inline CSS string
3. Run parse_declarations/css parsing separately to validate stylesheet strings during development

Example fix

# before (in styles.tcss)
# display: inline-block;
# after
display: block;

from textual.css.parse import parse_declarations
parse_declarations("display: block; opacity: 0.5;")  # smoke-test CSS in dev

from textual.css.stylesheet import DeclarationError
try:
    app.add_css(css_string)
except DeclarationError as e:
    report(f"bad rule {e.name} at {e.token}")

When it happens

Trigger: Any invalid TCSS declaration that reaches a processor: `display: inline-block;` (process_display), bad scalar units (scalar_error), unknown enum values (_process_enum) or multiple-keyword enums — all funnel through error().

Common situations: Errors in .tcss files or CSS strings passed to APP_CSS/push_screen styles; the traceback points here but the real cause is the named rule/token in the DeclarationError fields.

Related errors

• DeclarationError(error.name, error.token, error.message)
• failed to parse css; {error}
• unable to read CSS file {filename!r}
• StylesheetErrors(css_rules) (renderable summarizing CSS rule
• 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/f1c5982d8975010b. Report an issue: GitHub.