{"record":{"id":"e7fbf027daf6b09c","repo":"python-telegram-bot/python-telegram-bot","slug":"the-handlers-argument-must-be-a-sequence-of-hand","errorCode":null,"errorMessage":"The `handlers` argument must be a sequence of handlers or a dictionary where the keys are groups and values are sequences of handlers.","messagePattern":"The `handlers` argument must be a sequence of handlers or a dictionary where the keys are groups and values are sequences of handlers\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/telegram/ext/_application.py","lineNumber":1461,"sourceCode":"        if isinstance(handlers, dict) and not isinstance(group, DefaultValue):\n            raise TypeError(\"The `group` argument can only be used with a sequence of handlers.\")\n\n        if isinstance(handlers, dict):\n            for handler_group, grp_handlers in handlers.items():\n                if not isinstance(grp_handlers, Sequence):\n                    raise TypeError(\n                        f\"Handlers for group {handler_group} must be a sequence of handlers.\"\n                    )\n\n                for handler in grp_handlers:\n                    self.add_handler(handler, handler_group)\n\n        elif isinstance(handlers, Sequence):\n            for handler in handlers:\n                self.add_handler(handler, DefaultValue.get_value(group))\n\n        else:\n            raise TypeError(\n                \"The `handlers` argument must be a sequence of handlers or a \"\n                \"dictionary where the keys are groups and values are sequences of handlers.\"\n            )\n\n    def remove_handler(\n        self, handler: BaseHandler[Any, CCT, Any], group: int = DEFAULT_GROUP\n    ) -> None:\n        \"\"\"Remove a handler from the specified group.\n\n        Hint:\n            This method currently has no influence on calls to :meth:`process_update` that are\n            already in progress.\n\n            .. warning::\n                This behavior should currently be considered an implementation detail and not as\n                guaranteed behavior.\n\n        Args:","sourceCodeStart":1443,"sourceCodeEnd":1479,"githubUrl":"https://github.com/python-telegram-bot/python-telegram-bot/blob/d3b69d2e9fb7af6c796f84516cfda751752c7cb7/src/telegram/ext/_application.py#L1443-L1479","documentation":"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.","triggerScenarios":"`app.add_handlers(handler)` (single instance, not a sequence); passing a set `{h1, h2}`; passing a generator expression; passing a class instead of instances.","commonSituations":"Assuming add_handlers accepts one handler; passing a set built from deduplication; passing a str because it is technically a Sequence of handler names.","solutions":["Wrap single handlers in a list: `app.add_handlers([handler])`","Convert sets/generators to lists first","Use a dict of group -> list when groups differ"],"exampleFix":"# before\napp.add_handlers(handler)\n\n# after\napp.add_handlers([handler])","handlingStrategy":"type-guard","validationCode":"from collections.abc import Sequence\nassert isinstance(handlers, (Sequence, dict)) and not isinstance(handlers, str)","typeGuard":"from collections.abc import Sequence\n\ndef is_valid_handlers_arg(h) -> bool:\n    if isinstance(h, str):\n        return False\n    return isinstance(h, (Sequence, dict))","tryCatchPattern":null,"preventionTips":["Pass lists of handler instances","Convert sets/generators to lists first"],"tags":["handlers","typeerror","api-misuse"],"backgroundTag":"invalid-argument-type","analyzedSha":"d3b69d2e9fb7af6c796f84516cfda751752c7cb7","analyzedAt":"2026-08-28T16:18:54.805Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}