Textualize/textual · warning · UnknownModeError

Unknown mode {mode!r}

Error message

Unknown mode {mode!r}

What it means

UnknownModeError raised by App.remove_mode when the named mode is not in self._modes — it was never registered or already removed.

Source

Thrown at src/textual/app.py:2714

            )
        self._modes[mode] = base_screen

    def remove_mode(self, mode: str) -> AwaitComplete:
        """Removes a mode from the app.

        Screens that are running in the stack of that mode are scheduled for pruning.

        Args:
            mode: The mode to remove. It can't be the active mode.

        Raises:
            ActiveModeError: If trying to remove the active mode.
            UnknownModeError: If trying to remove an unknown mode.
        """
        if mode == self._current_mode:
            raise ActiveModeError(f"Can't remove active mode {mode!r}")
        elif mode not in self._modes:
            raise UnknownModeError(f"Unknown mode {mode!r}")
        else:
            del self._modes[mode]

        if mode not in self._screen_stacks:
            return AwaitComplete.nothing()

        stack = self._screen_stacks[mode]
        del self._screen_stacks[mode]

        async def remove_screens() -> None:
            """Remove screens."""
            for screen in reversed(stack):
                await self._replace_screen(screen)

        return AwaitComplete(remove_screens()).call_next(self)

    def is_screen_installed(self, screen: Screen | str) -> bool:
        """Check if a given screen has been installed.

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Guard with membership check: if mode in app._modes and mode != app._current_mode: await app.remove_mode(mode)
2. Catch textual.app.UnknownModeError for fire-and-forget cleanup

Example fix

# before
await app.remove_mode("editor")  # may not exist

# after
if "editor" in app._modes:
    await app.remove_mode("editor")

if mode in app._modes:
    await app.remove_mode(mode)

try:
    await app.remove_mode(mode)
except UnknownModeError:
    pass  # already gone

When it happens

Trigger: await app.remove_mode("editor") when 'editor' is not a key of _modes; double-removal; typo in name.

Common situations: Cleanup code that removes modes defensively but blindly; races where another task already removed the mode.

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}
• No known mode {self._current_mode!r}
• MODES cannot contain instances, use a type instead (got inst

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