sgl-project/sglang · error · ValueError

shape ratio must be a positive finite number

Error message

shape ratio must be a positive finite number

What it means

After width/height pass finiteness checks, their ratio must itself be a positive finite number. In practice this only fires for degenerate float cases (e.g. width=5e-324 with height huge making the ratio underflow to 0, or overflow to inf).

Source

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

    base_short_edge = _validate_base_short_edge(base_short_edge)
    try:
        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

View on GitHub (pinned to 0132848349)

Solutions

1. Pass true pixel dimensions, not normalized/unitless fractions
2. Clamp inputs to a sane pixel range (e.g. 1..100000) before resolving

Example fix

# before
resolve_spatial_shape(width=0.0001, height=10000.0, ...)
# after
resolve_spatial_shape(width=1920, height=1080, ...)

import math
def ratio_finite(w, h):
    try: r = float(w) / float(h); return math.isfinite(r) and r > 0
    except (TypeError, ValueError, ZeroDivisionError): return False

def has_finite_ratio(w, h) -> bool:
    import math
    try:
        r = float(w) / float(h)
        return math.isfinite(r) and r > 0
    except Exception:
        return False

null

When it happens

Trigger: Calling minimax_h3_resolve_spatial_shape with extremely tiny/huge dimension pairs whose division underflows to 0.0 or overflows to inf despite both inputs being finite and positive.

Common situations: Denormalized float dimensions from a buggy scaler; passing values in the wrong units (e.g. normalized 0.0001 fractions).

Related errors

• target.short_edge must be an integer, got {value!r}
• target.short_edge must be a positive integer, got {value!r}
• shape width and height must be positive finite numbers
• adapt_shape_v1 ratio must be within the inclusive range 1:4
• fl2va requires first_frame, last_frame, or both

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