Textualize/textual · error · StyleValueError

invalid percentage value '{token}'

Error message

invalid percentage value '{token}'

What it means

ColorProperty accepts color strings that may include a percentage alpha token like `rgb(255,0,0) 50%`. When the percentage token cannot be parsed as a percentage (percentage_string_to_float raises ValueError), this StyleValueError names the offending token. Only simple integer/float percentages are accepted.

Source

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

        Raises:
            ColorParseError: When the color string is invalid.
        """
        _rich_traceback_omit = True
        if color is None:
            if obj.clear_rule(self.name):
                obj.refresh(children=True)
        elif isinstance(color, Color):
            if obj.set_rule(self.name, color):
                obj.refresh(children=True)
        elif isinstance(color, str):
            alpha = 1.0
            parsed_color = Color(255, 255, 255)
            for token in color.split():
                if token.endswith("%"):
                    try:
                        alpha = percentage_string_to_float(token)
                    except ValueError:
                        raise StyleValueError(f"invalid percentage value '{token}'")
                    continue
                try:
                    parsed_color = Color.parse(token)
                except ColorParseError as error:
                    raise StyleValueError(
                        f"Invalid color value '{token}'",
                        help_text=color_property_help_text(
                            self.name, context="inline", error=error, value=token
                        ),
                    )
            parsed_color = parsed_color.multiply_alpha(alpha)

            if obj.set_rule(self.name, parsed_color):
                obj.refresh(children=True)
        else:
            raise StyleValueError(f"Invalid color value {color}")

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Fix the percentage token to a plain form like `50%`
2. If you meant opacity, ensure it is a number followed by a single ASCII % character

Example fix

# before
styles.color = "red 5O%"
# after
styles.color = "red 50%"

import re
if re.fullmatch(r"\d+(\.\d+)?%", tok):
    styles.color = f"red {tok}"

try:
    styles.color = value
except StyleValueError as e:
    log.warning("bad color: %s", e)

When it happens

Trigger: `styles.color = "red 5O%"` (letter O), `"red 150 %%"`, or `"#ff0000 0.5%"` where the percent component is malformed; also non-ASCII percent signs or whitespace inside the token.

Common situations: Typos in the percent sign, localized keyboards producing a full-width ％ character, or copy-pasted color strings from other formats.

Related errors

• Invalid color value {color}
• Expected a str, Path or list[str | Path] for the CSS_PATH.
• {self.name} must be one of {friendly_list(self._valid_values
• {self.name} must be a str
• unknown word {word!r} in style flags

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