{"record":{"id":"e6e7a5ad17bcd88a","repo":"sgl-project/sglang","slug":"adapt-shape-v1-ratio-must-be-within-the-inclusive","errorCode":null,"errorMessage":"adapt_shape_v1 ratio must be within the inclusive range 1:4 to 4:1, got {source_width:g}:{source_height:g}","messagePattern":"adapt_shape_v1 ratio must be within the inclusive range 1:4 to 4:1, got (.+?):(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py","lineNumber":148,"sourceCode":"        source_width = float(width)\n        source_height = float(height)\n    except (TypeError, ValueError) as exc:\n        raise ValueError(\n            \"shape 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(\"shape width and height must be positive finite numbers\")\n\n    ratio = source_width / source_height\n    if not math.isfinite(ratio) or ratio <= 0.0:\n        raise ValueError(\"shape ratio must be a positive finite number\")\n    if not MINIMAX_H3_MIN_ASPECT_RATIO <= ratio <= MINIMAX_H3_MAX_ASPECT_RATIO:\n        raise ValueError(\n            \"adapt_shape_v1 ratio must be within the inclusive range \"\n            f\"1:4 to 4:1, got {source_width:g}:{source_height:g}\"\n        )\n\n    if ratio >= 1.0:\n        nominal_width = float(base_short_edge) * ratio\n        nominal_height = float(base_short_edge)\n    else:\n        nominal_width = float(base_short_edge)\n        nominal_height = float(base_short_edge) / ratio\n    nominal_area = nominal_width * nominal_height\n    if nominal_area > MINIMAX_H3_MAX_PIXELS:\n        size_mode = \"area\"\n        scale = math.sqrt(float(MINIMAX_H3_MAX_PIXELS) / nominal_area)\n        nominal_width *= scale\n        nominal_height *= scale\n    else:\n        size_mode = \"short_edge\"","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py#L130-L166","documentation":"MiniMax-H3 (adapt_shape_v1) only supports source aspect ratios within an inclusive 1:4 to 4:1 range. The width/height ratio outside [MINIMAX_H3_MIN_ASPECT_RATIO, MINIMAX_H3_MAX_ASPECT_RATIO] is rejected because the canvas alignment/pixel budget logic is only validated in that range.","triggerScenarios":"Calling minimax_h3_resolve_spatial_shape with e.g. a 2000x300 pixel panorama (ratio ~6.7) or a 100x1000 tall strip (ratio 0.1).","commonSituations":"Feeding ultra-wide panoramic or vertical-strip keyframes; keyframe cropping that accidentally produces extreme aspect ratios.","solutions":["Crop or letterbox the source so width/height is between 0.25 and 4.0","Pick a target aspect_ratio within range instead of deriving from an extreme source","Verify source dimensions before submission"],"exampleFix":"# before\nresolve_spatial_shape(width=4000, height=500, ...)\n# after\ncrop to 4000x1000 (4:1) or letterbox, then resolve_spatial_shape(width=4000, height=1000, ...)","handlingStrategy":"validation","validationCode":"def ratio_in_range(w, h):\n    return 0.25 <= (float(w) / float(h)) <= 4.0","typeGuard":"def is_supported_ratio(w, h) -> bool:\n    r = float(w) / float(h)\n    return 0.25 <= r <= 4.0","tryCatchPattern":"null","preventionTips":["Crop/letterbox extreme panoramas or vertical strips before submission"],"tags":["minimax-h3","aspect-ratio","range-check","spatial"],"backgroundTag":"value-out-of-range","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}