Expected a character or hatch value here; found {character!r

Error message

Expected a character or hatch value here; found {character!r}

What it means

The hatch property accepts either a single character or a named hatch from the HATCHES mapping, paired with a color. When the character portion is not length-1 and not a known hatch name, this ValueError is raised listing what was found. Hatch names are things like 'cross', 'half', 'solid' etc. defined in textual.css.constants.HATCHES.

Source

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

    def __set__(
        self, obj: StylesBase, value: tuple[str, Color | str] | Literal["none"] | None
    ) -> None:
        _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

Use a single character, e.g. `("|", "red")`
Use an exact HATCHES key name (check textual.css.constants.HATCHES)

Example fix

# before
styles.hatch = ("diaganol", "red")
# after
styles.hatch = ("\\", "red")

Defensive patterns

Strategy: validation

Validate before calling

from textual.css.constants import HATCHES
if len(ch) == 1 or ch in HATCHES:
    styles.hatch = (ch, color)

Type guard

def is_valid_hatch_char(ch: str) -> bool:
    return len(ch) == 1 or ch in HATCHES

Prevention

Reference HATCHES keys directly instead of typing hatch names

When it happens

Trigger: `styles.hatch = ("xx", "red")`, `styles.hatch = ("diaganol", "red")` (typo'd hatch name), or a multi-char string not in HATCHES.

Common situations: Misspelling hatch names, passing a full-line fill string, or not realizing a non-single character must be a registered hatch name.

Related errors

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