langchain-ai/deepagents · error · ChannelMediaError

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

Error message

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

What it means

While streaming the download in 64 KB chunks, `_download_file` tracks the running total and raises `ChannelMediaError` as soon as the bytes written would exceed `max_bytes`. It closes the file and unlinks the partial destination first, so no truncated file is left behind. This catches cases where the actual body exceeds the declared/checked size cap.

Source

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

        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:
    """Load the persisted getUpdates offset from disk.

    Args:
        offset_file: Path to the offset state file.

    Returns:
        Persisted offset value, or ``0`` if the file is missing or corrupt.
    """
    if not offset_file.is_file():
        return 0

View on GitHub (pinned to a1af029e6e)

Solutions

1. Raise `max_media_bytes` in the channel config.
2. Investigate why the response exceeded its declared size (proxy compression, redirect to a different file) and fix the fetch path.
3. Wrap the download in `except ChannelMediaError` and clean up / notify, which the code already partially does by unlinking the partial file.

Example fix

# before
max_bytes = 1024 * 1024  # 1 MB — too small for typical photos
# after
max_bytes = 20 * 1024 * 1024  # 20 MB

try:
    path = _download_file(response, destination, max_bytes)
except ChannelMediaError:
    logging.warning("stream exceeded cap of %d bytes; partial file removed", max_bytes)
    # destination already unlinked by _download_file

When it happens

Trigger: Server sends more body bytes than `max_bytes` (missing/lying Content-Length, chunked transfer), or the Content-Length pre-check passed but the stream exceeds the cap mid-download.

Common situations: Proxies or CDNs that don't honor Content-Length; attacks/malformed responses with endless bodies; legitimate media slightly larger than a tight `max_media_bytes` cap that the header check missed due to encoding differences.

Related errors

• Telegram media is too large: {file_size} bytes exceeds {self
• media file is too large: {expected} 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/c2a244c3ca5f4051. Report an issue: GitHub.