langchain-ai/deepagents · error · ChannelMediaError

media is too large: 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.

Solutions

1. Shrink the media (re-encode, lower bitrate/resolution) below `max_bytes`.
2. Raise the `max_bytes` argument or `DEEPAGENTS_TALON_MAX_MEDIA_BYTES` if the provider supports larger uploads.
3. 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)

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:
    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

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

• media file is too large
• media file is too large
• media file is too large
• media file type does not match requested type
• media path is not a regular file

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

Appendix: 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)