Textualize/textual · error · UnknownModeError

No known mode {self._current_mode!r}

Error message

No known mode {self._current_mode!r}

What it means

UnknownModeError raised by App.screen when the current mode name has no entry in _screen_stacks. This usually indicates internal state corruption: the active mode's stack was removed or never initialized.

Source

Thrown at src/textual/app.py:1639

    @property
    def animator(self) -> Animator:
        """The animator object."""
        return self._animator

    @property
    def screen(self) -> Screen[object]:
        """The current active screen.

        Returns:
            The currently active (visible) screen.

        Raises:
            ScreenStackError: If there are no screens on the stack.
        """
        try:
            return self._screen_stack[-1]
        except KeyError:
            raise UnknownModeError(f"No known mode {self._current_mode!r}") from None
        except IndexError:
            raise ScreenStackError("No screens on stack") from None

    @property
    def _background_screens(self) -> list[Screen]:
        """A list of screens that may be visible due to background opacity (top-most first, not including current screen)."""
        screens: list[Screen] = []
        for screen in reversed(self._screen_stack[:-1]):
            screens.append(screen)
            if screen.styles.background.a == 1:
                break
        background_screens = screens[::-1]
        return background_screens

    @property
    def size(self) -> Size:
        """The size of the terminal.

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Avoid removing the active mode; switch_mode away before remove_mode
2. Access app.screen only after on_mount has completed
3. If it persists, reproduce with a minimal app and report — often an internal invariant break

Example fix

# before
app.remove_mode("editor")  # while editor is current

# after
await app.switch_mode("main")
await app.remove_mode("editor")

if app._current_mode not in app._screen_stacks:
    await app.switch_mode('_default')  # recover

try:
    s = app.screen
except UnknownModeError:
    await app.switch_mode('main')
    s = app.screen

When it happens

Trigger: Accessing app.screen after remove_mode deleted the stack of the (still current) mode, or during early startup before the default stack exists.

Common situations: Calling remove_mode on the active mode from a worker, race between mode teardown and UI access.

Related errors

• {variable_name} should contain a Screen type or callable, no
• expected a callable or string, got {screen_object!r}
• No mode called {mode!r}
• MODES cannot contain instances, use a type instead (got inst
• No known mode {mode!r}

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