Textualize/textual · error · UnknownModeError

No known mode {mode!r}

Error message

No known mode {mode!r}

What it means

UnknownModeError raised by App.switch_mode when the target mode name is not in self._modes, i.e. not declared in the MODES class variable nor added via add_mode().

Source

Thrown at src/textual/app.py:2649

        """Switch to a given mode.

        Args:
            mode: The mode to switch to.

        Returns:
            An optionally awaitable object which waits for the screen associated
                with the mode to be mounted.

        Raises:
            UnknownModeError: If trying to switch to an unknown mode.

        """

        if mode == self._current_mode:
            return AwaitMount(self.screen, [])

        if mode not in self._modes:
            raise UnknownModeError(f"No known mode {mode!r}")

        self.delay_update()

        self.screen.post_message(events.ScreenSuspend())
        self.screen.refresh()

        if mode not in self._screen_stacks:
            await_mount = self._init_mode(mode)
        else:
            await_mount = AwaitMount(self.screen, [])

        self._current_mode = mode
        if self.screen._css_update_count != self._css_update_count:
            self.refresh_css()

        self.mode_change_signal.publish(mode)
        self.screen_change_signal.publish(self.screen)

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Declare the mode: add MODES = {"settings": SettingsScreen} to the App
2. Or at runtime: await app.add_mode("settings", SettingsScreen) before switching
3. Verify mode names programmatically before switching

Example fix

# before
class MyApp(App):
    MODES = {"main": MainScreen}
# later:
await app.switch_mode("settings")

# after
class MyApp(App):
    MODES = {"main": MainScreen, "settings": SettingsScreen}
await app.switch_mode("settings")

if mode not in app._modes:
    await app.add_mode(mode, DefaultScreen)
await app.switch_mode(mode)

try:
    await app.switch_mode(mode)
except UnknownModeError:
    await app.add_mode(mode, DefaultScreen)
    await app.switch_mode(mode)

When it happens

Trigger: await app.switch_mode("settings") with no "settings" key in MODES; typo in mode name; switching to a mode after remove_mode.

Common situations: Typos, dynamic mode names from config, or forgetting add_mode when modes are built at runtime.

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/4f645f5fd6a6aab8. Report an issue: GitHub.