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

The entity is neither Message nor Update (got: {type(entity)

Error message

The entity is neither Message nor Update (got: {type(entity)})

What it means

Raised by telegram.helpers.effective_message_type when the entity argument is neither a Message nor an Update instance. The function inspects the entity's attributes to determine which MessageType it contains, so it must receive one of those two types. Any other object (e.g. a CallbackQuery, User, or str) triggers this TypeError.

Source

Thrown at src/telegram/helpers.py:140

    Returns:
        :obj:`str` | :obj:`None`: One of :class:`telegram.constants.MessageType` if the entity
        contains a message that matches one of those types. :obj:`None` otherwise.

    """
    # Importing on file-level yields cyclic Import Errors
    from telegram import (  # pylint: disable=import-outside-toplevel  # noqa: PLC0415
        Message,
        Update,
    )

    if isinstance(entity, Message):
        message = entity
    elif isinstance(entity, Update):
        if not entity.effective_message:
            return None
        message = entity.effective_message
    else:
        raise TypeError(f"The entity is neither Message nor Update (got: {type(entity)})")

    for message_type in MessageType:
        if message[message_type]:
            return message_type

    return None


def create_deep_linked_url(
    bot_username: str, payload: str | None = None, group: bool = False
) -> str:
    """
    Creates a deep-linked URL for this :paramref:`~create_deep_linked_url.bot_username` with the
    specified :paramref:`~create_deep_linked_url.payload`. See
    https://core.telegram.org/bots/features#deep-linking to learn more.

    The :paramref:`~create_deep_linked_url.payload` may consist of the following characters:
    ``A-Z, a-z, 0-9, _, -``

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Pass update directly instead of a sub-object like update.callback_query or update.message where message may be None
2. If you have a CallbackQuery, use entity.message instead
3. Type-check before calling: isinstance(entity, (Message, Update))

Example fix

// before
type_ = effective_message_type(update.callback_query)
// after
type_ = effective_message_type(update)  # or update.callback_query.message

from telegram import Message, Update
if not isinstance(entity, (Message, Update)):
    raise TypeError(f'unsupported entity: {type(entity)}')

from telegram import Message, Update

def is_message_or_update(e: object) -> bool:
    return isinstance(e, (Message, Update))

try:
    t = effective_message_type(entity)
except TypeError as e:
    logger.warning('unsupported entity: %s', e)
    t = None

When it happens

Trigger: Calling effective_message_type(entity) with anything other than telegram.Message or telegram.Update, e.g. passing update.callback_query or a plain string.

Common situations: Passing the wrong sub-object of an Update (like update.channel_post vs update itself), or refactoring handlers so a non-Update object reaches this helper.

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

• CommandHandler argument has_args cannot be a negative intege
• callback_data_json is not in the required format
• Unable to deserialize conversations_json. Not valid JSON
• `rate_limit_args` can only be used if a `ExtBot.rate_limiter
• The `pattern` must not be a coroutine function! Use an ordin

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