Textualize/textual · error

Hatch character must have a cell length of 1

Error message

Hatch character must have a cell length of 1

What it means

After resolving a hatch character (possibly via HATCHES), Textual verifies its terminal cell width is exactly 1 using cell_len. Zero-width or double-width characters (combining marks, CJK, emoji) raise this ValueError even if the input is a single Python character.

Source

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

        _rich_traceback_omit = True
        if value is None:
            if obj.clear_rule("hatch"):
                obj.refresh(children=True)
            return

        if value == "none":
            hatch = "none"
        else:
            character, color = value
            if len(character) != 1:
                try:
                    character = HATCHES[character]
                except KeyError:
                    raise ValueError(
                        f"Expected a character or hatch value here; found {character!r}"
                    ) from None
            if cell_len(character) != 1:
                raise ValueError("Hatch character must have a cell length of 1")
            if isinstance(color, str):
                color = Color.parse(color)
            hatch = (character, color)

        obj.set_rule("hatch", hatch)

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Stick to ASCII characters with cell width 1 (e.g. '-', '/', '|', '.')
2. Use named HATCHES values which are pre-validated

Example fix

# before
styles.hatch = ("中", "red")
# after
styles.hatch = ("/", "red")

from rich.cells import cell_len
if cell_len(ch) == 1:
    styles.hatch = (ch, color)

def is_cell_width_one(ch: str) -> bool:
    from rich.cells import cell_len
    return cell_len(ch) == 1

When it happens

Trigger: `styles.hatch = ("中", "red")` (double-width), a combining character like '\u0301', or a zero-width space — each is one char but cell_len != 1.

Common situations: Using non-ASCII characters from international keyboards or emoji as hatch fills without considering terminal cell width.

Related errors

• Expected a character or hatch value here; found {character!r
• 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
• invalid percentage value '{token}'

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