{"record":{"id":"22a27ebfcc2f3c7e","repo":"sgl-project/sglang","slug":"minimax-h3-image-material-is-invalid","errorCode":null,"errorMessage":"MiniMax H3 image material is invalid","messagePattern":"MiniMax H3 image material is invalid","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":377,"sourceCode":"    This is deliberately a model-facing validity check: it verifies that the\n    source is non-empty, parseable and contains the stream type requested by\n    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}\")","sourceCodeStart":359,"sourceCodeEnd":395,"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#L359-L395","documentation":"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.","triggerScenarios":"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.","commonSituations":"Corrupted uploads, files renamed to .jpg without conversion, truncated transfers, or non-image content delivered under an image material URI.","solutions":["Open the file locally with PIL (python -c \"from PIL import Image; Image.open('f').verify()\") to reproduce","Re-export the image as a valid JPEG/PNG/WEBP and retry","Verify the material URI actually points at the intended file (see 2201/2202 errors)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from PIL import Image\nwith Image.open(path) as im:\n    im.verify()  # raises on corrupt images","typeGuard":"def is_decodable_image(path: str) -> bool:\n    try:\n        with Image.open(path) as im:\n            im.verify()\n        return True\n    except Exception:\n        return False","tryCatchPattern":"try:\n    minimax_h3_localize_material_uri(uri)\nexcept ValueError as e:\n    if \"image material is invalid\" in str(e):\n        quarantine(uri)","preventionTips":["Run Image.verify() on uploads at ingest time","Checksum materials after transfer"],"tags":["minimax-h3","image-decode","pil","corrupt-file"],"backgroundTag":"image-decode-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}