Textualize/textual · error · ThemeDoesNotExist

{theme!r} is not a builtin theme, or it has not been registe

Error message

{theme!r} is not a builtin theme, or it has not been registered. To use a custom theme, register it first using `register_theme`, then switch to that theme by setting the `TextArea.theme` attribute.

What it means

Raised by TextArea._set_theme when the requested theme is neither in TextArea's registered themes dict nor among TextAreaTheme.get_builtin_theme() results. It suggests registering custom themes via register_theme before assigning TextArea.theme.

Source

Thrown at src/textual/widgets/_text_area.py:1014

    def _watch_theme(self, theme: str) -> None:
        """We set the styles on this widget when the theme changes, to ensure that
        if padding is applied, the colors match."""
        self._set_theme(theme)

    def _app_theme_changed(self) -> None:
        self._set_theme(self._theme.name)

    def _set_theme(self, theme: str) -> None:
        theme_object: TextAreaTheme | None

        # If the user supplied a string theme name, find it and apply it.
        try:
            theme_object = self._themes[theme]
        except KeyError:
            theme_object = TextAreaTheme.get_builtin_theme(theme)
            if theme_object is None:
                raise ThemeDoesNotExist(
                    f"{theme!r} is not a builtin theme, or it has not been registered. "
                    f"To use a custom theme, register it first using `register_theme`, "
                    f"then switch to that theme by setting the `TextArea.theme` attribute."
                ) from None

        self._theme = dataclasses.replace(theme_object)
        if theme_object:
            base_style = theme_object.base_style
            if base_style:
                color = base_style.color
                background = base_style.bgcolor
                if color:
                    self.styles.color = Color.from_rich_color(color)
                if background:
                    self.styles.background = Color.from_rich_color(background)
            else:
                # When the theme doesn't define a base style (e.g. the `css` theme),
                # the TextArea background/color should fallback to its CSS colors.

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Register first: build a TextAreaTheme and call TextArea.register_theme(theme), then set text_area.theme = theme.name.
2. For builtin themes, use the exact name from TextAreaTheme builtin themes (e.g. 'css', 'dracula', 'vscode_dark', 'monokai').
3. Check for typos/case in the theme name.

Example fix

# before
text_area.theme = 'my-theme'  # not registered
# after
from textual.widgets.text_area import TextAreaTheme, TextArea
TextArea.register_theme(TextAreaTheme(name='my-theme', ...))
text_area.theme = 'my-theme'

from textual.widgets.text_area import TextAreaTheme
if theme_name not in text_area._themes and TextAreaTheme.get_builtin_theme(theme_name) is None:
    TextArea.register_theme(my_theme)

from textual.widgets.text_area import ThemeDoesNotExist
try:
    text_area.theme = name
except ThemeDoesNotExist:
    text_area.theme = 'css'  # fallback

When it happens

Trigger: text_area.theme = 'my-theme' without calling TextArea.register_theme(theme) first; misspelling a builtin name like 'drakula' instead of 'dracula'.

Common situations: Creating custom syntax themes, typos in builtin names, or assuming a theme from another Textual API (app themes) applies to TextArea.

Related errors

• Theme {theme_name!r} has not been registered. Call 'App.regi
• tree-sitter is available, but no built-in or user-registered
• Can't animate attribute {attribute!r} on {obj!r}; attribute
• Don't know how to animate {value!r}; Can only animate <int>,
• Can't encode {datum!r}

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