Textualize/textual · error · ValueError

Value does not match template!

Error message

Value does not match template!

What it means

A ValueError raised by MaskedInput.validate_value when a reactive value does not satisfy the current _template.check(). It signals that the widget's value was set programmatically (or via reactive update) to a string that does not fit the mask, e.g. wrong length or characters in wrong slots.

Source

Thrown at src/textual/widgets/_masked_input.py:511

            classes=classes,
            disabled=disabled,
            compact=compact,
        )

        self._template = _Template(self, template)
        self.template = template

        value, _ = self._template.insert_separators(value or "", 0)
        self.value = value
        if tooltip is not None:
            self.tooltip = tooltip

    def validate_value(self, value: str) -> str:
        """Validates value against template."""
        if self._template is None:
            return value
        if not self._template.check(value, True):
            raise ValueError("Value does not match template!")
        return value[: len(self._template.mask)]

    def _watch_template(self, template: str) -> None:
        """Revalidate when template changes."""
        self._template = _Template(self, template) if template else None
        if self.is_mounted:
            self._watch_value(self.value)

    def _watch_placeholder(self, placeholder: str) -> None:
        """Update template display mask when placeholder changes."""
        if self._template is not None:
            self._template.update_mask(placeholder)
            self.refresh()

    def validate(self, value: str) -> ValidationResult | None:
        """Run all the validators associated with this MaskedInput on the supplied value.

        Same as `Input.validate()` but also validates against template which acts as an

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Format the value to the template before assigning (correct length and slot characters).
2. When changing templates, also set a compatible value in the same update.
3. Sanitize loaded data (strip separators, re-pad) or leave value empty and prefill via user/default handling.
4. Catch ValueError around programmatic value assignment during data load.

Example fix

# before
masked.value = '1234567890'  # template '999-9999'

# after
masked.value = '123-4567'  # matches template

if masked.template and len(masked.value.replace(masked.blank, '')) != expected_len:
    masked.value = ''  # reset instead of assigning mismatched value

try:
    masked.value = loaded_value
except ValueError:
    masked.value = ''

When it happens

Trigger: Setting masked_input.value = '123' when the template is '999-9999'; assigning a value saved from a different template before the template reactive updates; programmatically populating from a database field with inconsistent formatting.

Common situations: Loading stored values into an editing form where old data doesn't match the current mask; changing the template reactive while an old value remains; trimming/normalizing values incorrectly before assignment.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Template must contain at least one non-separator character
• {self.name} must be a str (e.g. '10%') or a float (e.g. 0.1)
• Expected a character or hatch value here; found {character!r
• {token!r} is not a valid scalar
• {name!r} is an invalid {description}; identifiers must conta

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