langchain-ai/deepagents · error · ChannelMediaError

{media.media_type} media is too large: {size} bytes exceeds

Error message

{media.media_type} media is too large: {size} bytes exceeds {max_bytes}

What it means

`_validate_media_size` is the private final step of `validate_media`; when a per-media `max_bytes` is configured and the file's size exceeds it, it raises `ChannelMediaError` naming the media type, actual byte size, and the cap. Unlike the generic cap helper, the message is prefixed with the media type for clearer user feedback.

Source

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

    Returns:
        The string if it is a non-empty ``str``, otherwise ``None``.
    """
    return value if isinstance(value, str) and value else None


def _validate_media_size(
    media: ChannelMedia,
    *,
    path: Path,
    max_bytes: int | None = None,
) -> ChannelMedia:
    if max_bytes is None:
        return ChannelMedia(path=path, media_type=media.media_type, caption=media.caption)
    size = path.stat().st_size
    if size > max_bytes:
        msg = f"{media.media_type} media is too large: {size} bytes exceeds {max_bytes}"
        raise ChannelMediaError(msg)

    return ChannelMedia(path=path, media_type=media.media_type, caption=media.caption)


def _is_self_message(message: ChannelMessage, operator_ids: frozenset[str]) -> bool:
    if message.metadata.get("from_self") is True:
        return True
    return message.sender_id is not None and message.sender_id in operator_ids


def _matches_text(text: str, patterns: tuple[str, ...]) -> bool:
    return any(fnmatch.fnmatchcase(text, pattern) for pattern in patterns)


def _exposure_mode(value: str, *, provider: str) -> ExposureMode:
    try:
        return ExposureMode(value)
    except ValueError as error:

View on GitHub (pinned to a1af029e6e)

Solutions

Shrink the media (re-encode, lower bitrate/resolution) below `max_bytes`.
Raise the `max_bytes` argument or `DEEPAGENTS_TALON_MAX_MEDIA_BYTES` if the provider supports larger uploads.
Catch `ChannelMediaError` and reply to the sender that the attachment exceeds the limit.

Example fix

# before
validate_media(media, max_bytes=16 * 1024 * 1024)  # voice note cap

# after
validate_media(transcode_to_opus(media, max_bytes=16 * 1024 * 1024), max_bytes=16 * 1024 * 1024)

Defensive patterns

Strategy: validation

Validate before calling

path = Path(media.path)
if max_bytes is not None and path.stat().st_size > max_bytes:
    raise ValueError(f'{media.media_type} exceeds {max_bytes} bytes')

Try / catch

try:
    await channel.send_media(media)
except ChannelMediaError as exc:
    if 'too large' in str(exc):
        await channel.send_text(f'{media.media_type} attachment is too large to send.')
    else:
        raise

Prevention

Transcode media per provider limits (voice notes, images) before send.
Pass explicit `max_bytes` per media type matching the provider's documented cap.
Log sizes at send time to catch creeping file sizes in CI-generated artifacts.

When it happens

Trigger: Calling `validate_media` (from `send_media`) with a `max_bytes` limit where `path.stat().st_size > max_bytes`. When `max_bytes` is None this check is skipped entirely.

Common situations: Provider-specific limits (e.g. WhatsApp voice-note caps) exceeded by generated audio; inbound/outbound images over a configured limit; large screenshots.

Related errors

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