langchain-ai/deepagents · error · ChannelMediaError

media file is too large: {expected} bytes exceeds {max_bytes

Error message

media file is too large: {expected} bytes exceeds {max_bytes}

What it means

`_download_file` validates the `Content-Length` header before streaming: if the server-declared length (`expected`) exceeds `max_bytes`, it raises `ChannelMediaError` immediately, avoiding a doomed download. This is the pre-flight half of the media size cap, complementing the streaming check.

Source

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

    Raises:
        ChannelMediaError: If the remote file exceeds `max_bytes`.
    """
    destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
    request = urllib.request.Request(url)  # noqa: S310  # URL constructed from Bot API config.
    with urllib.request.urlopen(  # noqa: S310  # download URL from Telegram API.
        request,
        timeout=timeout,
    ) as response:
        length = response.headers.get("content-length")
        if length is not None:
            try:
                expected = int(length)
            except ValueError:
                expected = None
            if expected is not None and expected > max_bytes:
                msg = f"media file is too large: {expected} bytes exceeds {max_bytes}"
                raise ChannelMediaError(msg)

        total = 0
        with destination.open("wb") as file:
            while chunk := response.read(64 * 1024):
                total += len(chunk)
                if total > max_bytes:
                    file.close()
                    destination.unlink(missing_ok=True)
                    msg = f"media file is too large: {total} bytes exceeds {max_bytes}"
                    raise ChannelMediaError(msg)
                file.write(chunk)
    destination.chmod(0o600)


# --- Offset persistence (ticket 23) ---


def _load_offset(offset_file: Path) -> int:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Increase `max_media_bytes` in the Talon config to a value covering your expected media sizes.
2. Skip or reject the attachment upstream by checking file size (see the `get_file` result) before invoking the download.
3. Catch `ChannelMediaError` around downloads and surface a user-friendly 'file too large' message.

Example fix

# before
cfg.max_media_bytes = 10 * 1024 * 1024
# after
cfg.max_media_bytes = 50 * 1024 * 1024

import urllib.request
def declared_size_ok(url: str, max_bytes: int) -> bool:
    req = urllib.request.Request(url, method="HEAD")
    with urllib.request.urlopen(req) as resp:
        length = resp.headers.get("Content-Length")
        return length is None or int(length) <= max_bytes

try:
    _download_file(response, destination, max_bytes)
except ChannelMediaError:
    destination.unlink(missing_ok=True)
    logging.warning("media download exceeded %d bytes; aborted", max_bytes)

When it happens

Trigger: Downloading a Telegram file whose HTTP response declares a Content-Length larger than `max_bytes`; called from `_download_file` (exercised by `test_download_file_aborts_when_stream_exceeds_cap`).

Common situations: Large videos whose Telegram CDN response reports a big Content-Length; misconfigured `max_media_bytes` smaller than legitimate media; server responses with gzip/transfer quirks producing an inflated declared length.

Related errors

• Telegram media is too large: {file_size} bytes exceeds {self
• 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
• Server graph '{graph_name}' failed readiness check (status:

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