langchain-ai/deepagents · error · ChannelMediaError

unsupported media file type: {path}

Error message

unsupported media file type: {path}

What it means

`_media_type` uses Python's `mimetypes.guess_type` to classify a media attachment by file extension. If the OS mimetype database cannot map the filename to a MIME type (unknown or missing extension), the function raises `ChannelMediaError` because the channel cannot determine whether the file is an image or video.

Source

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

        f"{config.open_ack}={config.open_ack_value} to acknowledge this risk"
    )
    raise ValueError(msg)


def _split_index(text: str, limit: int) -> int:
    window = text[:limit]
    for delimiter in ("\n\n", "\n", " "):
        index = window.rfind(delimiter)
        if index > 0:
            return index + len(delimiter)
    return limit


def _media_type(path: Path) -> str:
    mime, _ = mimetypes.guess_type(path)
    if mime is None:
        msg = f"unsupported media file type: {path}"
        raise ChannelMediaError(msg)
    if mime.startswith("image/"):
        return "image"
    if mime.startswith("video/"):
        return "video"
    msg = f"unsupported media mime type: {mime}"
    raise ChannelMediaError(msg)


_RETRYABLE_ERROR_FRAGMENTS = frozenset(
    {
        "connectionerror",
        "connectionreset",
        "connectionrefused",
        "connecttimeout",
        "timeout",
        "broken pipe",
        "remotedisconnected",
        "eoferror",

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rename the file to include a standard extension matching its actual type (e.g. `.jpg`, `.png`, `.mp4`) before validating.
2. Only send media types the channel supports (images and videos); strip or skip unsupported attachments before calling `validate_media`.
3. If the type is known but the extension is missing, copy the file to a name with the correct extension in your ingestion pipeline.

Example fix

# before
path = Path('/tmp/telegram_media/photo_001')  # no extension -> ChannelMediaError
# after
path = Path('/tmp/telegram_media/photo_001.jpg')

import mimetypes
from pathlib import Path
def has_supported_media_extension(path: Path) -> bool:
    mime, _ = mimetypes.guess_type(path)
    return mime is not None and mime.startswith(("image/", "video/"))

def is_media_file(path: Path) -> bool:
    mime, _ = mimetypes.guess_type(path)
    return mime is not None and mime.startswith(("image/", "video/"))

try:
    media_type = validate_media(path)
except ChannelMediaError as exc:
    logging.warning("skipping attachment %s: %s", path, exc)

When it happens

Trigger: Calling `validate_media` on a file whose name has no recognizable extension (e.g. `attachment`, `blob`, or a dotfile like `.preview`), so `mimetypes.guess_type(path)` returns `(None, None)`.

Common situations: Telegram senders upload files without extensions; downloaded media saved under opaque temp names; exotic formats not in the system mime database; files renamed during forwarding losing their extension.

Related errors

• unsupported media mime type: {mime}
• media file type {detected!r} does not match requested type {
• media file is too large: {size} bytes exceeds {max_bytes}
• {media.media_type} media is too large: {size} bytes exceeds
• unsupported outbound media file type: {path}

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