Textualize/textual · error · StyleValueError

{self.name} must be a str (e.g. '10%') or a float (e.g. 0.1)

Error message

{self.name} must be a str (e.g. '10%') or a float (e.g. 0.1)

What it means

FractionalProperty (used by rules like `opacity`, and other 0–1 fractional styles) accepts a number (int/float) or a percentage string such as '10%'. Any other value — a bare non-percent string like '0.5', None, or an object — raises StyleValueError explaining the two accepted forms.

Source

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

        Args:
            obj: The Styles object.
            value: The value to set as a float between 0 and 1, or
                as a percentage string such as '10%'.
        """
        _rich_traceback_omit = True
        name = self.name
        if value is None:
            if obj.clear_rule(name):
                obj.refresh(children=self.children)
            return

        if isinstance(value, (int, float)):
            float_value = float(value)
        elif isinstance(value, str) and value.endswith("%"):
            float_value = float(Scalar.parse(value).value) / 100
        else:
            raise StyleValueError(
                f"{self.name} must be a str (e.g. '10%') or a float (e.g. 0.1)",
                help_text=fractional_property_help_text(name, context="inline"),
            )
        if obj.set_rule(name, clamp(float_value, 0, 1)):
            obj.refresh(children=self.children)


class AlignProperty:
    """Combines the horizontal and vertical alignment properties into a single property."""

    def __set_name__(self, owner: StylesBase, name: str) -> None:
        self.horizontal = f"{name}_horizontal"
        self.vertical = f"{name}_vertical"

    def __get__(
        self, obj: StylesBase, type: type[StylesBase]
    ) -> tuple[AlignHorizontal, AlignVertical]:
        horizontal = getattr(obj, self.horizontal)

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Pass a float/int (`0.5`, `1`) or a percent string (`'50%'`)
2. Convert numeric strings from config with float() before assignment

Example fix

# before
styles.opacity = "0.5"
# after
styles.opacity = 0.5  # or "50%"

if isinstance(v, (int, float)) or (isinstance(v, str) and v.endswith("%")):
    styles.opacity = v
else:
    styles.opacity = float(v)

When it happens

Trigger: `styles.opacity = "0.5"` (string without %), `styles.opacity = "50 percent"`, `styles.opacity = None`, or `opacity: half;` in TCSS.

Common situations: Assuming any numeric string parses; reading values from config where numbers arrive as strings without conversion.

Related errors

• Expected a character or hatch value here; found {character!r
• {token!r} is not a valid scalar
• 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

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