sgl-project/sglang · critical · RuntimeError

MiniMax H3 requires ffmpeg and ffprobe for media processing

Error message

MiniMax H3 requires ffmpeg and ffprobe for media processing and validated output delivery; missing executables: {', '.join(missing_media_tools)}. Install the ffmpeg system package before starting SGLang.

What it means

Raised by MiniMaxH3Pipeline.__init__ when either ffmpeg or ffprobe is not found on PATH (checked with shutil.which). The pipeline uses ffmpeg for media demux/decode and ffprobe to validate generated output before delivery, so it refuses to start without both.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines/minimax_h3_pipeline.py:62

        "audio_vae",
        # scheduler intentionally absent: model_index carries scheduler=null;
        # per-modality sigma schedules are generated in TimestepPreparation
        # from the task profile, and the loop scheduler math lives in
        # scheduling_minimax_h3_euler_ancestral (stages accept scheduler=None).
        "transformer",
    ]

    def __init__(self, *args, **kwargs):
        # TODO: Enable this check on ROCm after adding ffmpeg to the AMD Docker
        # image and CI dependency installer.
        if not current_platform.is_rocm():
            missing_media_tools = [
                executable
                for executable in ("ffmpeg", "ffprobe")
                if shutil.which(executable) is None
            ]
            if missing_media_tools:
                raise RuntimeError(
                    "MiniMax H3 requires ffmpeg and ffprobe for media processing "
                    "and validated output delivery; missing executables: "
                    f"{', '.join(missing_media_tools)}. Install the ffmpeg system "
                    "package before starting SGLang."
                )
        super().__init__(*args, **kwargs)

    @staticmethod
    def model_subfolder_for_variant(variant: str) -> str:
        if not isinstance(variant, str) or not variant.strip():
            raise ValueError("MiniMax H3 model variant must be a non-empty string")
        normalized = variant.strip().lower()
        subfolders = {
            "fl2va": "FL2VA",
            "ref2va": "Ref2VA",
        }
        try:
            return subfolders[normalized]

View on GitHub (pinned to 0132848349)

Solutions

1. Install ffmpeg via the system package manager (apt-get install -y ffmpeg / apk add ffmpeg / yum install ffmpeg) in the image or host before starting SGLang
2. Verify both binaries resolve: `which ffmpeg ffprobe` from the exact environment/PATH the server will run under
3. If using Docker, add the ffmpeg install to the image rather than relying on the host

Example fix

# before (slim image, no ffmpeg)
docker run sglang:slim ... --model minimax-h3

# after
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg
docker build ... && docker run ... --model minimax-h3

import shutil
missing = [x for x in ('ffmpeg', 'ffprobe') if shutil.which(x) is None]
if missing:
    raise SystemExit(f'install ffmpeg; missing: {missing}')

When it happens

Trigger: Starting the MiniMax H3 server in a container or venv image that omits the ffmpeg package; PATH scoped to a conda/venv that shadows or excludes system ffmpeg; slim Docker images (python:*-slim, distroless) without multimedia libs.

Common situations: Kubernetes/Docker deployments with minimal base images; CI runners lacking system packages; systems where ffmpeg exists only as a Python package (imageio-ffmpeg) rather than a binary on PATH.

Related errors

• MiniMax H3 model variant must be a non-empty string
• unsupported MiniMax H3 model variant {variant!r}; supported:
• MiniMax H3 --model-variant and --model-subfolder select diff
• MiniMax H3 loaded checkpoint partition does not match --mode
• MiniMaxH3Pipeline only supports monolithic deployment; disag

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