sgl-project/sglang · error · ValueError

{path}.aspect_ratio for task {profile.task!r} must be 'auto'

Error message

{path}.aspect_ratio for task {profile.task!r} must be 'auto' or one of {list(MINIMAX_H3_FINITE_ASPECT_RATIOS)!r}, got {aspect_ratio!r}

What it means

For T2VA/REF2VA tasks, aspect_ratio must be "auto" or a member of MINIMAX_H3_FINITE_ASPECT_RATIOS; anything else is rejected. This enumerates the finite supported ratios (e.g. '16:9', '9:16', '1:1', ...).

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py:107

        raise ValueError(f"{path}.short_edge must be positive, got {short_edge}")
    if short_edge != MINIMAX_H3_RECOMMENDED_SHORT_EDGE:
        # Same guard the resolver applies. Without it the recommended value warns
        # that it is "outside the verified configuration", naming itself as the
        # verified one.
        warn_unverified_short_edge(short_edge)
    aspect_ratio = _require_str(target.get("aspect_ratio"), f"{path}.aspect_ratio")
    if profile.aspect_ratio_forced_auto and aspect_ratio != "auto":
        raise ValueError(
            f'{path}.aspect_ratio must be "auto" for task {profile.task!r}, '
            f"got {aspect_ratio!r}"
        )
    has_duration = target.get("duration_seconds") is not None
    if (
        profile.task in {MINIMAX_H3_TASK_T2VA, MINIMAX_H3_TASK_REF2VA}
        and aspect_ratio != "auto"
        and aspect_ratio not in MINIMAX_H3_FINITE_ASPECT_RATIOS
    ):
        raise ValueError(
            f"{path}.aspect_ratio for task {profile.task!r} must be 'auto' or "
            f"one of {list(MINIMAX_H3_FINITE_ASPECT_RATIOS)!r}, got "
            f"{aspect_ratio!r}"
        )
    if not has_duration:
        if not profile.duration_from_audio_reference:
            raise ValueError(f"{path}.duration_seconds is required")
        # ref2va: duration may derive from a reference audio; the
        # audio-condition presence is enforced after conditions validate.
    out: dict[str, Any] = {
        "short_edge": short_edge,
        "aspect_ratio": aspect_ratio,
    }
    if has_duration:
        duration = target["duration_seconds"]
        if isinstance(duration, bool) or not isinstance(duration, (int, float)):
            raise ValueError(f"{path}.duration_seconds must be a number")
        if duration <= 0:

View on GitHub (pinned to 0132848349)

Solutions

1. Use 'auto' to let the model pick the ratio
2. Use one of the entries in MINIMAX_H3_FINITE_ASPECT_RATIOS (import it and validate client-side)
3. Fix separator/format typos like '16x9' -> '16:9'

Example fix

// before
{"aspect_ratio": "16x9"}
// after
{"aspect_ratio": "16:9"}

from sglang... import MINIMAX_H3_FINITE_ASPECT_RATIOS
if ar != 'auto' and ar not in MINIMAX_H3_FINITE_ASPECT_RATIOS:
    raise ValueError(f'unsupported aspect_ratio {ar}')

def is_valid_aspect_ratio(v: str) -> bool:
    return v == 'auto' or v in MINIMAX_H3_FINITE_ASPECT_RATIOS

When it happens

Trigger: Passing aspect_ratio='4:3' or '21:9' or a typo like '16x9' on a t2va/ref2va request.

Common situations: Copy-pasting aspect ratios supported by other video models; using 'x' instead of ':' separators; locale-specific formatting.

Related errors

• unsupported MiniMax H3 condition type {condition_type!r}
• unsupported ref2va condition type {cond_type!r}
• reference image ratio must be within the inclusive range 1:4
• {path}.aspect_ratio must be "auto" for task {profile.task!r}
• {cpath}.role must be keyframe or reference, got {role!r}

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