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.

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)
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

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


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

Appendix: 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)