{"record":{"id":"b6369cdeecee9a46","repo":"sgl-project/sglang","slug":"reference-image-width-and-height-must-be-positive","errorCode":null,"errorMessage":"reference image width and height must be positive finite numbers","messagePattern":"reference image width and height must be positive finite numbers","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":142,"sourceCode":"\ndef minimax_h3_resolve_reference_image_shape(\n    *,\n    width: int | float,\n    height: int | float,\n) -> dict[str, Any]:\n    \"\"\"Resolve a ref2va image independently from the target canvas.\n\n    The image keeps its display ratio, always targets a 2048px short edge (even\n    when that requires upscaling), and rounds both dimensions independently to\n    the nearest 32px grid. Unlike target/video ``adapt_shape_v1``, reference\n    images have no area-cap branch.\n    \"\"\"\n\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)","sourceCodeStart":124,"sourceCodeEnd":160,"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#L124-L160","documentation":"minimax_h3_resolve_reference_image_shape converts width/height to floats and requires positive, finite values; non-numeric input, NaN, inf, or <= 0 is rejected. Used to resolve the reference image grid for queue preparation.","triggerScenarios":"Calling minimax_h3_resolve_reference_image_shape with width=None, \"1024\" (non-numeric string), NaN, or 0/negative dimensions.","commonSituations":"Missing metadata fields defaulting to None; image headers with zero dimensions (corrupt file); NaN leaking from failed EXIF parsing; string dims from JSON metadata.","solutions":["Validate dimensions are numeric, finite, and > 0 before calling","Read dimensions from the decoded image tensor/PIL image instead of trusting metadata","Sanitize NaN/None with sensible defaults or reject the sample upstream"],"exampleFix":"// before\nshape = minimax_h3_resolve_reference_image_shape(width=None, height=768, ...)\n// after\nshape = minimax_h3_resolve_reference_image_shape(width=1024, height=768, ...)","handlingStrategy":"validation","validationCode":"import math\nif not (isinstance(width, (int, float)) and isinstance(height, (int, float))\n        and math.isfinite(width) and math.isfinite(height)\n        and width > 0 and height > 0):\n    raise ValueError(\"invalid reference image dimensions\")","typeGuard":"def valid_dims(w, h) -> bool:\n    return isinstance(w, (int, float)) and isinstance(h, (int, float)) and math.isfinite(w) and math.isfinite(h) and w > 0 and h > 0","tryCatchPattern":"try:\n    shape = minimax_h3_resolve_reference_image_shape(w, h)\nexcept ValueError:\n    shape = fallback_shape  # e.g. from decoded PIL image","preventionTips":["Read dimensions from the decoded image, not metadata","Reject/repair corrupt images with zero or NaN dimensions upstream"],"tags":["minimax-h3","image-shape","validation"],"backgroundTag":"invalid-value-validation","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}