sgl-project/sglang · error · ValueError

adapt_shape_v1 ratio must be within the inclusive range 1:4

Error message

adapt_shape_v1 ratio must be within the inclusive range 1:4 to 4:1, got {source_width:g}:{source_height:g}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/resolved_plan.py:148

        source_width = float(width)
        source_height = float(height)
    except (TypeError, ValueError) as exc:
        raise ValueError(
            "shape width and height must be positive finite numbers"
        ) from exc
    if (
        not math.isfinite(source_width)
        or not math.isfinite(source_height)
        or source_width <= 0.0
        or source_height <= 0.0
    ):
        raise ValueError("shape width and height must be positive finite numbers")

    ratio = source_width / source_height
    if not math.isfinite(ratio) or ratio <= 0.0:
        raise ValueError("shape ratio must be a positive finite number")
    if not MINIMAX_H3_MIN_ASPECT_RATIO <= ratio <= MINIMAX_H3_MAX_ASPECT_RATIO:
        raise ValueError(
            "adapt_shape_v1 ratio must be within the inclusive range "
            f"1:4 to 4:1, got {source_width:g}:{source_height:g}"
        )

    if ratio >= 1.0:
        nominal_width = float(base_short_edge) * ratio
        nominal_height = float(base_short_edge)
    else:
        nominal_width = float(base_short_edge)
        nominal_height = float(base_short_edge) / ratio
    nominal_area = nominal_width * nominal_height
    if nominal_area > MINIMAX_H3_MAX_PIXELS:
        size_mode = "area"
        scale = math.sqrt(float(MINIMAX_H3_MAX_PIXELS) / nominal_area)
        nominal_width *= scale
        nominal_height *= scale
    else:
        size_mode = "short_edge"

View on GitHub (pinned to 0132848349)

Solutions

1. Crop or letterbox the source so width/height is between 0.25 and 4.0
2. Pick a target aspect_ratio within range instead of deriving from an extreme source
3. Verify source dimensions before submission

Example fix

# before
resolve_spatial_shape(width=4000, height=500, ...)
# after
crop to 4000x1000 (4:1) or letterbox, then resolve_spatial_shape(width=4000, height=1000, ...)

def ratio_in_range(w, h):
    return 0.25 <= (float(w) / float(h)) <= 4.0

def is_supported_ratio(w, h) -> bool:
    r = float(w) / float(h)
    return 0.25 <= r <= 4.0

null

When it happens

Trigger: Calling minimax_h3_resolve_spatial_shape with e.g. a 2000x300 pixel panorama (ratio ~6.7) or a 100x1000 tall strip (ratio 0.1).

Common situations: Feeding ultra-wide panoramic or vertical-strip keyframes; keyframe cropping that accidentally produces extreme aspect ratios.

Related errors

• noise_aug must be in [0, 1], got {noise_aug}
• reference image ratio must be within the inclusive range 1:4
• {path}.aspect_ratio must be "auto" for task {profile.task!r}
• {path}.aspect_ratio for task {profile.task!r} must be 'auto'
• {path}.duration_seconds must be in [{MINIMAX_H3_MIN_DURATION

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/e6e7a5ad17bcd88a. Report an issue: GitHub.