{"record":{"id":"95acb201a7cd3aeb","repo":"sgl-project/sglang","slug":"reference-image-ratio-must-be-within-the-inclusive","errorCode":null,"errorMessage":"reference image ratio must be within the inclusive range 1:4 to 4:1, got {source_width:g}x{source_height:g}","messagePattern":"reference image ratio must be within the inclusive range 1:4 to 4:1, got (.+?)x(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py","lineNumber":155,"sourceCode":"\n    try:\n        source_width = float(width)\n        source_height = float(height)\n    except (TypeError, ValueError) as exc:\n        raise ValueError(\n            \"reference image width and height must be positive finite numbers\"\n        ) from exc\n    if (\n        not math.isfinite(source_width)\n        or not math.isfinite(source_height)\n        or source_width <= 0.0\n        or source_height <= 0.0\n    ):\n        raise ValueError(\n            \"reference image width and height must be positive finite numbers\"\n        )\n    if source_width > 4.0 * source_height or source_height > 4.0 * source_width:\n        raise ValueError(\n            \"reference image ratio must be within the inclusive range \"\n            f\"1:4 to 4:1, got {source_width:g}x{source_height:g}\"\n        )\n\n    scale = MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE / min(source_width, source_height)\n    target_width = _nearest_multiple(\n        source_width * scale, MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE\n    )\n    target_height = _nearest_multiple(\n        source_height * scale, MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE\n    )\n    return {\n        \"geometry\": \"reference_image_resolved\",\n        \"shape_policy_version\": \"reference_image_short_edge_v1\",\n        \"base_short_edge\": MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE,\n        \"effective_short_edge\": min(target_width, target_height),\n        \"size_mode\": \"short_edge\",\n        \"multiple\": MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE,","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py#L137-L173","documentation":"MiniMax H3 enforces an aspect-ratio bound of 1:4 to 4:1 on reference images: the longer side may be at most four times the shorter side. This is a model-side constraint on the reference-image encoder and is checked during pre-queue shape resolution.","triggerScenarios":"Passing a reference image with an extreme aspect ratio, e.g. 1000x100 (10:1) or 200x2000, into minimax_h3_prepare_for_queue / the image reference chain.","commonSituations":"Users uploading panoramic strips, tall screenshots, banners, or any skinny elongated image as a style/identity reference.","solutions":["Crop or letterbox the image to within 1:4..4:1 before submitting (e.g. pad the short side)","Reject the request client-side with a clear aspect-ratio message","Center-crop to a bounded ratio such as 1:1 or 16:9 if padding is unacceptable"],"exampleFix":"// before\nimg = PIL.Image.open(path)  # 2000x200 -> ValueError downstream\n\n// after\nw, h = img.size\nif w > 4*h: img = img.crop((0,0,4*h,h))\nelif h > 4*w: img = img.crop((0,0,w,4*w))","handlingStrategy":"validation","validationCode":"def ratio_ok(w, h, limit=4.0) -> bool:\n    return w <= limit * h and h <= limit * w","typeGuard":null,"tryCatchPattern":"try:\n    minimax_h3_prepare_for_queue(batch)\nexcept ValueError as e:\n    if 'ratio' in str(e):\n        crop_to_ratio(image); retry=True\n    else:\n        raise","preventionTips":["Pad or crop extreme panoramas/tall screenshots client-side","Surface the 1:4..4:1 limit in the upload UI"],"tags":["minimax-h3","aspect-ratio","image-validation"],"backgroundTag":"image-aspect-ratio-limit","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}