sgl-project/sglang · error · ValueError

MiniMax H3 image material is invalid

Error message

MiniMax H3 image material is invalid

What it means

Wraps any exception thrown while opening/inspecting an image material with PIL (open failure, decode error, EXIF transpose failure, missing coded dimensions). Indicates the image bytes could not be interpreted at all.

Source

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

    This is deliberately a model-facing validity check: it verifies that the
    source is non-empty, parseable and contains the stream type requested by
    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}")

View on GitHub (pinned to 0132848349)

Solutions

1. Open the file locally with PIL (python -c "from PIL import Image; Image.open('f').verify()") to reproduce
2. Re-export the image as a valid JPEG/PNG/WEBP and retry
3. Verify the material URI actually points at the intended file (see 2201/2202 errors)

from PIL import Image
with Image.open(path) as im:
    im.verify()  # raises on corrupt images

def is_decodable_image(path: str) -> bool:
    try:
        with Image.open(path) as im:
            im.verify()
        return True
    except Exception:
        return False

try:
    minimax_h3_localize_material_uri(uri)
except ValueError as e:
    if "image material is invalid" in str(e):
        quarantine(uri)

When it happens

Trigger: Passing a condition_type='image' material whose bytes are not a decodable image (corrupt file, wrong extension, HTML error page saved as .jpg), causing PIL to raise inside the try block.

Common situations: Corrupted uploads, files renamed to .jpg without conversion, truncated transfers, or non-image content delivered under an image material URI.

Related errors

• fl2va requires first_frame, last_frame, or both
• ref2va requires at least one of reference_image, reference_v
• t2va takes no conditioning inputs; pick another task
• MiniMax-H3 quality="high" is validated only for the strict 4
• MiniMax-H3 on MPS requires synchronous layerwise offload for

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