sgl-project/sglang · error · ValueError

target.aspect_ratio must be 'W:H' or 'auto', got {value!r}

Error message

target.aspect_ratio must be 'W:H' or 'auto', got {value!r}

What it means

MiniMax-H3 parses target.aspect_ratio by splitting on ':' and expects exactly two parts ('W:H'). This error fires when the string has no colon, or more than one (e.g. 'auto', '16:9:2', '169').

Source

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

class MiniMaxH3ResolvedPlan(msgspec.Struct, frozen=True):
    task: str
    prompt: str
    seed: int | None
    materials: tuple[MiniMaxH3MaterialPlanItem, ...]
    encoders: dict
    branches: tuple[dict, ...]
    default_flow_shift: float
    default_audio_flow_shift: float
    flow_shift: float | None
    audio_flow_shift: float | None
    shape: dict
    condition_mask: dict


def _parse_aspect_ratio(value: str) -> tuple[int, int]:
    parts = value.split(":")
    if len(parts) != 2:
        raise ValueError(f"target.aspect_ratio must be 'W:H' or 'auto', got {value!r}")
    try:
        w, h = int(parts[0]), int(parts[1])
    except ValueError as exc:
        raise ValueError(
            f"target.aspect_ratio must be integer 'W:H', got {value!r}"
        ) from exc
    if w <= 0 or h <= 0:
        raise ValueError(
            f"target.aspect_ratio components must be positive, got {value!r}"
        )
    return w, h


def _nearest_multiple(value: float, multiple: int) -> int:
    return max(multiple, int(round(float(value) / multiple)) * multiple)


def _validate_base_short_edge(value: Any) -> int:

View on GitHub (pinned to 0132848349)

Solutions

1. Format the ratio as 'W:H' with a single colon, e.g. '16:9'
2. Use target aspect_ratio handling at the request-validation layer for 'auto' rather than in the resolved plan

Example fix

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

import re
def ratio_ok(v): return isinstance(v, str) and re.fullmatch(r"\d+:\d+", v) is not None

def is_wh_ratio(v) -> bool:
    import re
    return isinstance(v, str) and bool(re.fullmatch(r"[1-9]\d*:[1-9]\d*", v))

null

When it happens

Trigger: Calling minimax_h3_resolve_plan (via minimax_h3_plan_from_batch or directly) with a canonical whose target.aspect_ratio lacks exactly one ':' separator.

Common situations: Passing '16x9' or '169' instead of '16:9'; passing an empty string; assuming 'auto' is handled here (it is resolved earlier in _resolve_spatial).

Related errors

• target.aspect_ratio must be integer 'W:H', got {value!r}
• target.aspect_ratio components must be positive, got {value!
• data URI must contain a comma separator
• material URI has an invalid percent escape
• tar material URI must contain '<tar_path>:<encoded_header>'

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