sgl-project/sglang · error · RuntimeError

ffprobe is required to validate final MiniMax H3 output

Error message

ffprobe is required to validate final MiniMax H3 output

What it means

Final-output validation requires the ffprobe binary, which was not found on PATH (subprocess raised FileNotFoundError). Without ffprobe the adapter cannot verify the generated MP4's streams, resolution, or frame rate, so it refuses to return unvalidated output.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/video_adapter.py:387

                "-v",
                "error",
                "-show_entries",
                "stream=codec_type,codec_name,pix_fmt,width,height,avg_frame_rate,nb_frames,duration,sample_rate,channels:format=format_name,duration",
                "-of",
                "json",
                str(path),
            ],
            check=True,
            capture_output=True,
            text=True,
            timeout=30,
        )
    except subprocess.TimeoutExpired as exc:
        raise RuntimeError(
            "MiniMax H3 final output ffprobe timed out after 30 seconds"
        ) from exc
    except FileNotFoundError as exc:
        raise RuntimeError(
            "ffprobe is required to validate final MiniMax H3 output"
        ) from exc
    except subprocess.CalledProcessError as exc:
        detail = (exc.stderr or "").strip()
        suffix = f": {detail}" if detail else ""
        raise RuntimeError(
            f"ffprobe failed for final MiniMax H3 output{suffix}"
        ) from exc

    try:
        payload = json.loads(probe.stdout)
    except (TypeError, ValueError) as exc:
        raise RuntimeError(
            "ffprobe returned invalid JSON for MiniMax H3 output"
        ) from exc
    if not isinstance(payload, dict):
        raise RuntimeError("ffprobe returned invalid JSON for MiniMax H3 output")
    streams = payload.get("streams") or []

View on GitHub (pinned to 0132848349)

Solutions

Install ffmpeg (provides ffprobe): apt-get install -y ffmpeg (Debian/Ubuntu) or apk add ffmpeg (Alpine)
Verify with `ffprobe -version` using the same user/env as the server
If using conda: conda install -c conda-forge ffmpeg
Rebuild your Docker image with ffmpeg added

Example fix

# Dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*

Defensive patterns

Strategy: validation

Validate before calling

import shutil
if shutil.which("ffprobe") is None:
    raise EnvironmentError("install ffmpeg before running MiniMax H3 validation")

Prevention

Add `apt-get install -y ffmpeg` to Dockerfiles and CI images
Add a startup health check for ffprobe availability

When it happens

Trigger: Running the SGLang server/container in an image that does not include ffmpeg/ffprobe; PATH not including the ffmpeg install directory.

Common situations: Minimal Docker images (python:slim) without ffmpeg; slim CI environments; conda envs where ffmpeg is installed but not on the server's PATH.

Related errors

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