What causes "media file is too large: {size} bytes exceeds {max_bytes}" in langchain-ai/deepagents?

Compress or re-encode the media (e.g. transcode video, downscale images) under the cap.

langchain-ai/deepagents · error · ChannelMediaError

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

Error message

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

What it means

`validate_media_size` stats the media file and raises `ChannelMediaError` if its size exceeds the provided `max_bytes` cap. This enforces per-file size limits before attempting to upload media to a channel provider.

Source

Thrown at libs/talon/deepagents_talon/channels/base.py:324

        else:
            metadata.pop("voice_path", None)
    return replace(message, metadata=metadata)


def validate_media_size(path: Path, *, max_bytes: int) -> None:
    """Validate a local media file against the configured global cap.

    Args:
        path: Local media file to inspect.
        max_bytes: Maximum allowed media file size.

    Raises:
        ChannelMediaError: If the file exceeds `max_bytes`.
    """
    size = path.stat().st_size
    if size > max_bytes:
        msg = f"media file is too large: {size} bytes exceeds {max_bytes}"
        raise ChannelMediaError(msg)


def max_media_bytes_from_env(env: Mapping[str, str]) -> int:
    """Return the configured global media cap.

    Args:
        env: Environment variable mapping.

    Returns:
        Maximum media bytes allowed for channel media.

    Raises:
        ValueError: If the configured value is not a positive integer.
    """
    value = env.get(MAX_MEDIA_BYTES_ENV)
    if value is None:
        return DEFAULT_MAX_MEDIA_BYTES
    msg = f"{MAX_MEDIA_BYTES_ENV} must be a positive integer byte count"

View on GitHub (pinned to a1af029e6e)

Solutions

Compress or re-encode the media (e.g. transcode video, downscale images) under the cap.
Raise the cap via `DEEPAGENTS_TALON_MAX_MEDIA_BYTES` or the per-call `max_bytes` argument if your provider allows it.
Catch `ChannelMediaError` and notify the sender the attachment is too large, optionally splitting the content.

Example fix

# before
validate_media(media, max_bytes=50 * 1024 * 1024)  # 50MB

# after
validate_media(compress_if_needed(media, limit=50 * 1024 * 1024), max_bytes=50 * 1024 * 1024)

Defensive patterns

Strategy: validation

Validate before calling

path = Path(media.path)
size = path.stat().st_size
if size > max_bytes:
    raise ValueError(f'{path} is {size} bytes; cap is {max_bytes}')

Try / catch

try:
    await channel.send_media(media)
except ChannelMediaError as exc:
    if 'too large' in str(exc):
        await channel.send_text('That attachment exceeds the size limit; try compressing it.')
    else:
        raise

Prevention

Check `stat().st_size` before send and compress when near the limit.
Set `DEEPAGENTS_TALON_MAX_MEDIA_BYTES` to the smallest limit your providers actually allow.
Stream or chunk very large outputs instead of attaching them.

When it happens

Trigger: Calling `validate_media_size` (via `validate_media`/`send_media` or inbound `_enforce_inbound_media_cap`) with a file whose `st_size` is greater than `max_bytes` — e.g. a video larger than the provider/channel limit.

Common situations: Sending long screen recordings or large PDFs over WhatsApp/Telegram which cap uploads; inbound media from a user exceeding the global `DEEPAGENTS_TALON_MAX_MEDIA_BYTES` cap; default 1 GB cap exceeded.

Related errors

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