Textualize/textual · error · TypeError

MODES cannot contain instances, use a type instead (got inst

Error message

MODES cannot contain instances, use a type instead (got instance of {type(_screen).__name__} for {mode!r})

What it means

TypeError raised in App mode-switching code when a MODES entry is an instantiated Screen. At switch time Textual calls the entry (factory) to build the screen; an instance cannot be safely reused across mode activations.

Source

Thrown at src/textual/app.py:2605

        Args:
            mode: Name of the mode.

        Returns:
            An optionally awaitable object which can be awaited until the screen
            associated with the mode has been mounted.
        """

        stack = self._screen_stacks.get(mode, [])
        if stack:
            # Mode already exists
            # Return an dummy await
            return AwaitMount(stack[0], [])

        if mode in self._modes:
            # Mode is defined in MODES
            _screen = self._modes[mode]
            if isinstance(_screen, Screen):
                raise TypeError(
                    "MODES cannot contain instances, use a type instead "
                    f"(got instance of {type(_screen).__name__} for {mode!r})"
                )
            new_screen: Screen | str = _screen() if callable(_screen) else _screen
            screen, await_mount = self._get_screen(new_screen)
            stack.append(screen)
            self._load_screen_css(screen)
            if screen._css_update_count != self._css_update_count:
                self.refresh_css()

            screen.post_message(events.ScreenResume())
        else:
            # Mode is not defined
            screen = self.get_default_screen()
            stack.append(screen)
            self._register(self, screen)
            screen.post_message(events.ScreenResume())
            await_mount = AwaitMount(stack[0], [])

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Store the class or a callable: MODES = {"editor": EditorScreen}
2. Pass state via screen constructor through a lambda/partial factory: MODES = {"editor": lambda: EditorScreen(item)}
3. Alternatively use add_mode with a callable

Example fix

# before
class MyApp(App):
    MODES = {"editor": EditorScreen()}

# after
class MyApp(App):
    MODES = {"editor": EditorScreen}

assert not isinstance(MODES['editor'], Screen), 'MODES needs the class/factory'

def is_mode_factory(v) -> bool:
    return isinstance(v, str) or (callable(v) and not isinstance(v, Screen))

When it happens

Trigger: MODES = {"editor": EditorScreen(app)} and then switch_mode("editor").

Common situations: Trying to pass state into a mode by pre-instantiating the screen; works once in prototypes but violates the API contract.

Related errors

• expected a callable or string, got {screen_object!r}
• add_mode() must be called with a Screen type, not an instanc
• {variable_name} should contain a Screen type or callable, no
• No mode called {mode!r}
• No known mode {self._current_mode!r}

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