Textualize/textual · error · SelectionError

Only Selection or a prompt/value tuple is supported in Selec

Error message

Only Selection or a prompt/value tuple is supported in SelectionList

What it means

Raised by SelectionList.add_options when an item in the sequence is neither a Selection instance nor a tuple (tuples are forwarded to _make_selection). Any other type — a string, list, or arbitrary object — is rejected with SelectionError.

Source

Thrown at src/textual/widgets/_selection_list.py:670

        # things like a separator, or a base Option, being passed in. So we
        # extend the types of accepted items to keep mypy and friends happy,
        # but then we runtime check that we've been given sensible types (in
        # this case the supported tuple values).
        cleaned_options: list[Selection[SelectionType]] = []
        for item in items:
            if isinstance(item, tuple):
                cleaned_options.append(
                    self._make_selection(
                        cast(
                            "tuple[ContentText, SelectionType] | tuple[ContentText, SelectionType, bool]",
                            item,
                        )
                    )
                )
            elif isinstance(item, Selection):
                cleaned_options.append(self._make_selection(item))
            else:
                raise SelectionError(
                    "Only Selection or a prompt/value tuple is supported in SelectionList"
                )

        # Add the new items to the value mappings.
        self._values.update(
            {
                option.value: index
                for index, option in enumerate(cleaned_options, start=self.option_count)
            }
        )

        return super().add_options(cleaned_options)

    def add_option(
        self,
        item: (
            OptionListContent
            | Selection

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Convert each item to a Selection or a (prompt, value[, state]) tuple.
2. Use add_selection(...) APIs for single items where applicable.
3. For string-only lists use SelectionList([(s, s) for s in strings]).

Example fix

# before
SelectionList(['apples', 'pears'])
# after
SelectionList([('apples', 'apples'), ('pears', 'pears')])

items = [Selection(s, s) if isinstance(s, str) else s for s in items]

from textual.widgets.selection_list import Selection
def is_selection_item(x) -> bool: return isinstance(x, (Selection, tuple))

When it happens

Trigger: SelectionList(['just a string']) or add_options([['prompt', True]]) (list instead of tuple), or passing Option objects meant for OptionList.

Common situations: Mixing up OptionList and SelectionList APIs, passing plain strings for simple lists, or lists-of-lists from JSON instead of tuples.

Related errors

• Don't know how to animate {value!r}; Can only animate <int>,
• Can't encode {datum!r}
• must be bytes
• Query value is the wrong type; expected type {expect_type.__
• Query value is the wrong type; expected type {expect_type.__

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