python-telegram-bot/python-telegram-bot · error · TypeError

The `handlers` argument must be a sequence of handlers or a

Error message

The `handlers` argument must be a sequence of handlers or a dictionary where the keys are groups and values are sequences of handlers.

What it means

add_handlers() only accepts a Sequence of handlers or a dict of {group: sequence}. Any other type (a single handler object, a string, a set, an int, a generator) falls through to this TypeError.

Source

Thrown at src/telegram/ext/_application.py:1461

        if isinstance(handlers, dict) and not isinstance(group, DefaultValue):
            raise TypeError("The `group` argument can only be used with a sequence of handlers.")

        if isinstance(handlers, dict):
            for handler_group, grp_handlers in handlers.items():
                if not isinstance(grp_handlers, Sequence):
                    raise TypeError(
                        f"Handlers for group {handler_group} must be a sequence of handlers."
                    )

                for handler in grp_handlers:
                    self.add_handler(handler, handler_group)

        elif isinstance(handlers, Sequence):
            for handler in handlers:
                self.add_handler(handler, DefaultValue.get_value(group))

        else:
            raise TypeError(
                "The `handlers` argument must be a sequence of handlers or a "
                "dictionary where the keys are groups and values are sequences of handlers."
            )

    def remove_handler(
        self, handler: BaseHandler[Any, CCT, Any], group: int = DEFAULT_GROUP
    ) -> None:
        """Remove a handler from the specified group.

        Hint:
            This method currently has no influence on calls to :meth:`process_update` that are
            already in progress.

            .. warning::
                This behavior should currently be considered an implementation detail and not as
                guaranteed behavior.

        Args:

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Wrap single handlers in a list: `app.add_handlers([handler])`
2. Convert sets/generators to lists first
3. Use a dict of group -> list when groups differ

Example fix

# before
app.add_handlers(handler)

# after
app.add_handlers([handler])

from collections.abc import Sequence
assert isinstance(handlers, (Sequence, dict)) and not isinstance(handlers, str)

from collections.abc import Sequence

def is_valid_handlers_arg(h) -> bool:
    if isinstance(h, str):
        return False
    return isinstance(h, (Sequence, dict))

When it happens

Trigger: `app.add_handlers(handler)` (single instance, not a sequence); passing a set `{h1, h2}`; passing a generator expression; passing a class instead of instances.

Common situations: Assuming add_handlers accepts one handler; passing a set built from deduplication; passing a str because it is technically a Sequence of handler names.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• handler is not an instance of {BaseHandler.__name__}
• group is not int
• The `group` argument can only be used with a sequence of han
• Handlers for group {handler_group} must be a sequence of han
• Unable to convert {type(time_object).__name__} object to tim

AI-assisted analysis of python-telegram-bot/python-telegram-bot@d3b69d2e9f (2026-08-28). Data as JSON: /api/errors/e7fbf027daf6b09c. Report an issue: GitHub.