sgl-project/sglang · error · ValueError

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

Error message

{path}.aspect_ratio must be "auto" for task {profile.task!r}, got {aspect_ratio!r}

What it means

The task profile for this MiniMax-H3 request forces aspect_ratio to "auto" (profile.aspect_ratio_forced_auto), but the request supplied a different string. Only specific tasks (not the T2VA/REF2VA finite-ratio set) allow explicit aspect ratios; the forced-auto tasks must use 'auto'.

Source

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

def _validate_target(target: Any, *, profile: MiniMaxH3TaskProfile) -> dict[str, Any]:
    path = "target"
    if not isinstance(target, Mapping):
        raise ValueError(f"{path} is required and must be an object")
    # The canonical target has a deliberately small projection.  Transport
    # compatibility keys are ignored; only these three declared values are
    # validated and emitted below.
    short_edge = _require_int(target.get("short_edge"), f"{path}.short_edge")
    if short_edge <= 0:
        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

View on GitHub (pinned to 0132848349)

Solutions

1. Set target.aspect_ratio to the literal string "auto" for this task
2. Check the task profile's aspect_ratio_forced_auto flag before populating the field

Example fix

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

if profile.aspect_ratio_forced_auto:
    target['aspect_ratio'] = 'auto'

When it happens

Trigger: Submitting a task whose profile sets aspect_ratio_forced_auto (e.g. an audio-driven variant) with aspect_ratio like "16:9" instead of "auto".

Common situations: Reusing a T2VA request body for a forced-auto task; hardcoding a default aspect ratio in a client SDK for all tasks.

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/7b7edef3cc00c18f. Report an issue: GitHub.