langchain-ai/deepagents · error · ValueError

unsupported outbound media file type: {path}

Error message

unsupported outbound media file type: {path}

What it means

ValueError raised by outbound_channel_media when the referenced media file has an extension that does not map to a supported outbound media type (image/video/audio). The path is resolved against the outbound root first, then its type is classified via _outbound_media_type.

Source

Thrown at libs/talon/deepagents_talon/media.py:185

        root: Optional directory that must contain the referenced media. When
            supplied, Markdown references must be relative paths resolved inside
            this root.

    Returns:
        Channel media payload.

    Raises:
        ValueError: If the referenced path is unsafe or is not an image or video.
    """
    path = (
        resolve_bounded_media_path(ref.path, root, require_relative=True)
        if root is not None
        else ref.path.expanduser()
    )
    media_type = _outbound_media_type(path)
    if media_type is None:
        msg = f"unsupported outbound media file type: {path}"
        raise ValueError(msg)
    return ChannelMedia(path=path, media_type=media_type, caption=caption)


def resolve_bounded_media_path(
    path: Path,
    root: Path,
    *,
    require_relative: bool = False,
) -> Path:
    """Resolve a local media path and enforce containment under a trusted root.

    Args:
        path: Candidate media path.
        root: Directory that must contain the media after symlink resolution.
        require_relative: Whether to reject absolute candidate paths up front.

    Returns:
        Canonical media path under `root`.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Send only files with supported media extensions (images/videos/audio per _outbound_media_type)
2. Convert or rename the file to a supported format/type before sending
3. If the type should be supported, check the whitelist in media.py for the expected extension

Example fix

// before
ChannelMediaRef(path=Path("report.pdf"))
// after
ChannelMediaRef(path=Path("chart.png"))  # convert the pdf chart to a supported image

SUPPORTED = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".mp4", ".webm", ".mp3", ".ogg", ".wav"}
if path.suffix.lower() not in SUPPORTED:
    raise ValueError(f"unsupported media type: {path.suffix}")

def is_supported_media(path: Path) -> bool:
    from deepagents_talon.media import _outbound_media_type
    return _outbound_media_type(path) is not None

try:
    media = outbound_channel_media(ref)
except ValueError as exc:
    logger.warning("Skipping attachment: %s", exc)
    media = None

When it happens

Trigger: Passing a ChannelMediaRef whose file is e.g. .txt, .pdf, .docx, or has no recognizable extension to outbound_channel_media (via _outbound_media_from_refs).

Common situations: Attaching generated artifacts (logs, spreadsheets) to a chat message; a file saved without an extension; an extension the library does not whitelist.

Related errors

• 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 media file type: {path}
• unsupported media mime type: {mime}

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