sgl-project/sglang · error · ValueError

.role must be keyframe or reference, got

Error message

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

What it means

Request validation: condition role must be 'keyframe' or 'reference'. Fix the role field.

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

• {cpath}: {exc}
• has unknown fields
• must be an object
• .start_time_seconds is only allowed for video or…
• allows at most entries for task

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

Appendix: 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)