sgl-project/sglang · error · ValueError

MiniMax H3 image material uses an unsupported format

Error message

MiniMax H3 image material uses an unsupported format

What it means

After successfully decoding the image, its PIL format is not one of JPEG, PNG, or WEBP. MiniMax H3's image pipeline only accepts these three encodings.

Source

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

    the condition.  Generic transport/resource ceilings do not belong here;
    the model's shape and temporal contracts are resolved separately.
    """

    if condition_type == "image":
        try:
            from PIL import Image, ImageOps

            with Image.open(path) as image:
                coded_width, coded_height = image.size
                image_format = str(image.format or "").upper()
                if coded_width <= 0 or coded_height <= 0:
                    raise ValueError("image has no positive dimensions")
                display_image = ImageOps.exif_transpose(image)
                width, height = display_image.size
        except Exception as exc:
            raise ValueError("MiniMax H3 image material is invalid") from exc
        if image_format not in {"JPEG", "PNG", "WEBP"}:
            raise ValueError("MiniMax H3 image material uses an unsupported format")
        if width <= 0 or height <= 0:
            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)

View on GitHub (pinned to 0132848349)

Solutions

  1. Convert the image: convert in.png -quality 90 out.jpg (or to WEBP/PNG)
  2. Update your producer/uploader to only emit JPEG/PNG/WEBP
  3. For HEIC/AVIF sources, convert on the client before upload rather than relying on server-side support

Example fix

# before
material = MiniMaxH3Material(path="photo.heic", condition_type="image")
# after
from PIL import Image
Image.open("photo.heic").save("photo.jpg", quality=90)
material = MiniMaxH3Material(path="photo.jpg", condition_type="image")
Defensive patterns

Strategy: validation

Validate before calling

from PIL import Image
with Image.open(path) as im:
    assert im.format in {"JPEG", "PNG", "WEBP"}, f"bad format {im.format}"

Type guard

def is_supported_image(path: str) -> bool:
    try:
        with Image.open(path) as im:
            return im.format in {"JPEG", "PNG", "WEBP"}
    except Exception:
        return False

Try / catch

try:
    minimax_h3_localize_material_uri(uri)
except ValueError as e:
    if "unsupported format" in str(e):
        convert_and_retry(path)

Prevention

When it happens

Trigger: A valid image in another format — GIF, BMP, TIFF, AVIF, HEIC, or a raw PPM — supplied as an image material.

Common situations: Phone photos in HEIC, screenshots saved as TIFF/BMP, animated GIFs, or codecs unsupported by the build's PIL.

Related errors

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