sgl-project/sglang · error · ValueError

MiniMax H3 media material is invalid

Error message

MiniMax H3 media material is invalid

What it means

Running ffprobe on the media material failed (ffprobe not found, non-zero exit, unparseable output). The library wraps any exception from _ffprobe_media into this error.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py:399

            raise ValueError(
                "MiniMax H3 image material has no positive display geometry"
            )
        return {
            "condition_type": "image",
            "coded_width": int(coded_width),
            "coded_height": int(coded_height),
            "display_width": int(width),
            "display_height": int(height),
            "image_format": image_format,
            "exif_transposed": (coded_width, coded_height) != (width, height),
        }

    if condition_type not in {"audio", "video", "video_audio"}:
        raise ValueError(f"unsupported MiniMax H3 condition type {condition_type!r}")
    try:
        payload = _ffprobe_media(path)
    except Exception as exc:
        raise ValueError("MiniMax H3 media material is invalid") from exc

    streams = payload.get("streams") or []
    format_names = set(
        str((payload.get("format") or {}).get("format_name") or "").split(",")
    )
    allowed_formats = {
        "mov",
        "mp4",
        "m4a",
        "3gp",
        "3g2",
        "mj2",
        "matroska",
        "webm",
        "wav",
        "mp3",
        "flac",
        "ogg",

View on GitHub (pinned to 0132848349)

Solutions

  1. Verify ffprobe is installed and on PATH: ffprobe -version
  2. If corrupt, re-encode or re-fetch the media file
  3. In Docker images, add ffmpeg (apt-get install -y ffmpeg)

Example fix

# Dockerfile
# before
FROM python:3.12-slim
# after
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg
Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, subprocess
assert shutil.which("ffprobe"), "ffprobe not on PATH"
subprocess.run(["ffprobe", "-v", "error", path], check=True)

Try / catch

try:
    minimax_h3_localize_material_uri(uri)
except ValueError as e:
    if "media material is invalid" in str(e):
        log_ffprobe_env(); raise

Prevention

When it happens

Trigger: condition_type is audio/video/video_audio and ffprobe is missing from PATH, times out, or the file is not a media container ffprobe can read.

Common situations: Container/image without ffmpeg installed, PATH not including ffmpeg's bin dir in the serving environment, or a corrupt/non-media file passed as audio/video material.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/a80da80684170d78. Report an issue: GitHub.