langchain-ai/deepagents · error · ChannelMediaError

Telegram media is too large: {file_size} bytes exceeds {self

Error message

Telegram media is too large: {file_size} bytes exceeds {self.config.max_media_bytes}

What it means

Before downloading an inbound Telegram attachment, `_download_inbound_media` checks the file size reported by the Telegram API (`get_file` result) against `config.max_media_bytes`. Files whose declared size exceeds the cap raise `ChannelMediaError` so oversized media is never written to disk.

Source

Thrown at libs/talon/deepagents_talon/channels/telegram.py:660

            media_type: Normalized media category.
            message_id: Telegram message identifier used to name the file.

        Returns:
            Local path to the downloaded file.
        """
        payload = await self._transport.call("getFile", file_id=file_id)
        result = _extract_result(payload)
        file_path = result.get("file_path") if isinstance(result, dict) else None
        if not isinstance(file_path, str):
            msg = "Telegram getFile response missing file_path"
            raise _TelegramError(msg)
        file_size = result.get("file_size") if isinstance(result, dict) else None
        if isinstance(file_size, int) and file_size > self.config.max_media_bytes:
            msg = (
                "Telegram media is too large: "
                f"{file_size} bytes exceeds {self.config.max_media_bytes}"
            )
            raise ChannelMediaError(msg)
        if self.config.inbound_media_dir is None:
            msg = "Telegram inbound media directory is not configured"
            raise _TelegramError(msg)
        suffix = _safe_suffix(file_path, media_type)
        destination = self.config.inbound_media_dir / _inbound_media_filename(
            message_id=message_id,
            file_id=file_id,
            suffix=suffix,
        )
        download_url = f"{self.config.api_base}/file/bot{self.config.bot_token}/{file_path}"
        await asyncio.to_thread(
            _download_file,
            download_url,
            destination,
            self.config.request_timeout_seconds,
            self.config.max_media_bytes,
        )
        return destination

View on GitHub (pinned to a1af029e6e)

Solutions

1. Raise `max_media_bytes` in the Talon config to accommodate the media sizes your users send (mind disk and memory constraints).
2. Ask senders to compress media or use Telegram's compressed photo/video send modes, which produce smaller files.
3. Handle `ChannelMediaError` in your inbound pipeline and reply to the sender that the attachment is too large instead of crashing the handler.

Example fix

# before
config.max_media_bytes = 5 * 1024 * 1024  # 5 MB cap
# after
config.max_media_bytes = 20 * 1024 * 1024  # 20 MB cap

def inbound_size_ok(file_size: int | None, max_bytes: int) -> bool:
    return file_size is None or file_size <= max_bytes

try:
    media = await channel._prepare_inbound_media(message)
except ChannelMediaError as exc:
    await reply(message, f"Attachment rejected: {exc}")

When it happens

Trigger: A user sends a photo/video to the bot whose Telegram-reported `file_size` exceeds the configured `max_media_bytes` limit; `_prepare_inbound_media` then aborts during message ingestion.

Common situations: Users send large videos to the bot; deployments with a conservative `max_media_bytes` (e.g. a few MB) receiving normal-sized media; bots in busy groups receiving forwarded large files.

Related errors

• media file is too large: {expected} bytes exceeds {max_bytes
• media file is too large: {total} bytes exceeds {max_bytes}
• media file is too large: {size} bytes exceeds {max_bytes}
• {media.media_type} media is too large: {size} bytes exceeds
• {label} is {actual} characters; maximum is {limit}. Remove a

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/5caff2e0a013b42c. Report an issue: GitHub.