{"record":{"id":"62dc896887ba6d78","repo":"sgl-project/sglang","slug":"minimax-h3-image-material-uses-an-unsupported-form","errorCode":null,"errorMessage":"MiniMax H3 image material uses an unsupported format","messagePattern":"MiniMax H3 image material uses an unsupported format","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py","lineNumber":379,"sourceCode":"    the condition.  Generic transport/resource ceilings do not belong here;\n    the model's shape and temporal contracts are resolved separately.\n    \"\"\"\n\n    if condition_type == \"image\":\n        try:\n            from PIL import Image, ImageOps\n\n            with Image.open(path) as image:\n                coded_width, coded_height = image.size\n                image_format = str(image.format or \"\").upper()\n                if coded_width <= 0 or coded_height <= 0:\n                    raise ValueError(\"image has no positive dimensions\")\n                display_image = ImageOps.exif_transpose(image)\n                width, height = display_image.size\n        except Exception as exc:\n            raise ValueError(\"MiniMax H3 image material is invalid\") from exc\n        if image_format not in {\"JPEG\", \"PNG\", \"WEBP\"}:\n            raise ValueError(\"MiniMax H3 image material uses an unsupported format\")\n        if width <= 0 or height <= 0:\n            raise ValueError(\n                \"MiniMax H3 image material has no positive display geometry\"\n            )\n        return {\n            \"condition_type\": \"image\",\n            \"coded_width\": int(coded_width),\n            \"coded_height\": int(coded_height),\n            \"display_width\": int(width),\n            \"display_height\": int(height),\n            \"image_format\": image_format,\n            \"exif_transposed\": (coded_width, coded_height) != (width, height),\n        }\n\n    if condition_type not in {\"audio\", \"video\", \"video_audio\"}:\n        raise ValueError(f\"unsupported MiniMax H3 condition type {condition_type!r}\")\n    try:\n        payload = _ffprobe_media(path)","sourceCodeStart":361,"sourceCodeEnd":397,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py#L361-L397","documentation":"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.","triggerScenarios":"A valid image in another format — GIF, BMP, TIFF, AVIF, HEIC, or a raw PPM — supplied as an image material.","commonSituations":"Phone photos in HEIC, screenshots saved as TIFF/BMP, animated GIFs, or codecs unsupported by the build's PIL.","solutions":["Convert the image: convert in.png -quality 90 out.jpg (or to WEBP/PNG)","Update your producer/uploader to only emit JPEG/PNG/WEBP","For HEIC/AVIF sources, convert on the client before upload rather than relying on server-side support"],"exampleFix":"# before\nmaterial = MiniMaxH3Material(path=\"photo.heic\", condition_type=\"image\")\n# after\nfrom PIL import Image\nImage.open(\"photo.heic\").save(\"photo.jpg\", quality=90)\nmaterial = MiniMaxH3Material(path=\"photo.jpg\", condition_type=\"image\")","handlingStrategy":"validation","validationCode":"from PIL import Image\nwith Image.open(path) as im:\n    assert im.format in {\"JPEG\", \"PNG\", \"WEBP\"}, f\"bad format {im.format}\"","typeGuard":"def is_supported_image(path: str) -> bool:\n    try:\n        with Image.open(path) as im:\n            return im.format in {\"JPEG\", \"PNG\", \"WEBP\"}\n    except Exception:\n        return False","tryCatchPattern":"try:\n    minimax_h3_localize_material_uri(uri)\nexcept ValueError as e:\n    if \"unsupported format\" in str(e):\n        convert_and_retry(path)","preventionTips":["Enforce JPEG/PNG/WEBP at upload boundaries","Convert HEIC/TIFF client-side"],"tags":["minimax-h3","image-format","unsupported-format"],"backgroundTag":"unsupported-image-format","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}