sgl-project/sglang · error · ValueError

{cpath}.role must be keyframe or reference, got {role!r}

Error message

{cpath}.role must be keyframe or reference, got {role!r}

What it means

A condition's role must be exactly 'keyframe' or 'reference' (the constants MINIMAX_H3_CONDITION_ROLE_KEYFRAME/REFERENCE); anything else, including typos and singulars like 'frame', is rejected.

Source

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

    aligned_frame_count = (
        minimax_h3_align_frame_count(frame_count) if frame_count is not None else None
    )
    normalized: list[dict[str, Any]] = []
    seen_frame_indices: dict[int, int] = {}
    for index, cond in enumerate(conditions):
        cpath = f"{path}[{index}]"
        if not isinstance(cond, Mapping):
            raise ValueError(f"{cpath} must be an object")
        unknown = set(cond) - _ALLOWED_CONDITION_KEYS
        if unknown:
            raise ValueError(f"{cpath} has unknown fields: {sorted(unknown)}")
        role = _require_str(cond.get("role"), f"{cpath}.role")
        if role not in (
            MINIMAX_H3_CONDITION_ROLE_KEYFRAME,
            MINIMAX_H3_CONDITION_ROLE_REFERENCE,
        ):
            raise ValueError(
                f"{cpath}.role must be keyframe or reference, " f"got {role!r}"
            )
        cond_type = _require_str(cond.get("type"), f"{cpath}.type")
        try:
            rule = profile.rule_for(role=role, condition_type=cond_type)
        except ValueError as exc:
            raise ValueError(f"{cpath}: {exc}") from exc
        uri = _require_str(cond.get("uri"), f"{cpath}.uri")

        entry: dict[str, Any] = {"type": cond_type, "uri": uri, "role": role}
        if rule.requires_frame_index:
            frame_index = _require_int(cond.get("frame_index"), f"{cpath}.frame_index")
            if aligned_frame_count is None:
                raise ValueError(
                    f"{cpath}.frame_index requires a resolved target duration"
                )
            if frame_index == -1:
                resolved = aligned_frame_count - 1

View on GitHub (pinned to 0132848349)

Solutions

1. Use the exact lowercase strings 'keyframe' or 'reference'
2. Import the role constants rather than hardcoding

Example fix

// before
{"role": "REFERENCE", ...}
// after
{"role": "reference", ...}

if cond['role'] not in ('keyframe', 'reference'):
    raise ValueError('bad role')

def is_valid_role(v: str) -> bool:
    return v in ('keyframe', 'reference')

When it happens

Trigger: role: "frames", "REFERENCE" (case-sensitive), or "first_frame".

Common situations: Guessing role names; case mismatch; using another model's role vocabulary.

Related errors

• unsupported MiniMax H3 condition type {condition_type!r}
• unsupported ref2va condition type {cond_type!r}
• {path}.aspect_ratio for task {profile.task!r} must be 'auto'
• {path} must be a list
• {path} must be empty for task {profile.task!r} (got {len(con

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