sgl-project/sglang · error · ValueError

reference image width and height must be positive finite num

Error message

reference image width and height must be positive finite numbers

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py:142

def minimax_h3_resolve_reference_image_shape(
    *,
    width: int | float,
    height: int | float,
) -> dict[str, Any]:
    """Resolve a ref2va image independently from the target canvas.

    The image keeps its display ratio, always targets a 2048px short edge (even
    when that requires upscaling), and rounds both dimensions independently to
    the nearest 32px grid. Unlike target/video ``adapt_shape_v1``, reference
    images have no area-cap branch.
    """

    try:
        source_width = float(width)
        source_height = float(height)
    except (TypeError, ValueError) as exc:
        raise ValueError(
            "reference image 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(
            "reference image width and height must be positive finite numbers"
        )
    if source_width > 4.0 * source_height or source_height > 4.0 * source_width:
        raise ValueError(
            "reference image ratio must be within the inclusive range "
            f"1:4 to 4:1, got {source_width:g}x{source_height:g}"
        )

    scale = MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE / min(source_width, source_height)

View on GitHub (pinned to 0132848349)

Solutions

1. Validate dimensions are numeric, finite, and > 0 before calling
2. Read dimensions from the decoded image tensor/PIL image instead of trusting metadata
3. Sanitize NaN/None with sensible defaults or reject the sample upstream

Example fix

// before
shape = minimax_h3_resolve_reference_image_shape(width=None, height=768, ...)
// after
shape = minimax_h3_resolve_reference_image_shape(width=1024, height=768, ...)

import math
if not (isinstance(width, (int, float)) and isinstance(height, (int, float))
        and math.isfinite(width) and math.isfinite(height)
        and width > 0 and height > 0):
    raise ValueError("invalid reference image dimensions")

def valid_dims(w, h) -> bool:
    return isinstance(w, (int, float)) and isinstance(h, (int, float)) and math.isfinite(w) and math.isfinite(h) and w > 0 and h > 0

try:
    shape = minimax_h3_resolve_reference_image_shape(w, h)
except ValueError:
    shape = fallback_shape  # e.g. from decoded PIL image

When it happens

Trigger: Calling minimax_h3_resolve_reference_image_shape with width=None, "1024" (non-numeric string), NaN, or 0/negative dimensions.

Common situations: Missing metadata fields defaulting to None; image headers with zero dimensions (corrupt file); NaN leaking from failed EXIF parsing; string dims from JSON metadata.

Related errors

• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 AdaLN cache has invalid timestep plans
• TP size must be positive.
• num_attention_heads must be positive.
• hidden_size must be positive.

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