{"record":{"id":"46ddacfc29b729b3","repo":"sgl-project/sglang","slug":"cpath-role-must-be-keyframe-or-reference-got-r","errorCode":null,"errorMessage":"{cpath}.role must be keyframe or reference, got {role!r}","messagePattern":"(.+?)\\.role must be keyframe or reference, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py","lineNumber":198,"sourceCode":"\n    aligned_frame_count = (\n        minimax_h3_align_frame_count(frame_count) if frame_count is not None else None\n    )\n    normalized: list[dict[str, Any]] = []\n    seen_frame_indices: dict[int, int] = {}\n    for index, cond in enumerate(conditions):\n        cpath = f\"{path}[{index}]\"\n        if not isinstance(cond, Mapping):\n            raise ValueError(f\"{cpath} must be an object\")\n        unknown = set(cond) - _ALLOWED_CONDITION_KEYS\n        if unknown:\n            raise ValueError(f\"{cpath} has unknown fields: {sorted(unknown)}\")\n        role = _require_str(cond.get(\"role\"), f\"{cpath}.role\")\n        if role not in (\n            MINIMAX_H3_CONDITION_ROLE_KEYFRAME,\n            MINIMAX_H3_CONDITION_ROLE_REFERENCE,\n        ):\n            raise ValueError(\n                f\"{cpath}.role must be keyframe or reference, \" f\"got {role!r}\"\n            )\n        cond_type = _require_str(cond.get(\"type\"), f\"{cpath}.type\")\n        try:\n            rule = profile.rule_for(role=role, condition_type=cond_type)\n        except ValueError as exc:\n            raise ValueError(f\"{cpath}: {exc}\") from exc\n        uri = _require_str(cond.get(\"uri\"), f\"{cpath}.uri\")\n\n        entry: dict[str, Any] = {\"type\": cond_type, \"uri\": uri, \"role\": role}\n        if rule.requires_frame_index:\n            frame_index = _require_int(cond.get(\"frame_index\"), f\"{cpath}.frame_index\")\n            if aligned_frame_count is None:\n                raise ValueError(\n                    f\"{cpath}.frame_index requires a resolved target duration\"\n                )\n            if frame_index == -1:\n                resolved = aligned_frame_count - 1","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/request_validation.py#L180-L216","documentation":"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.","triggerScenarios":"role: \"frames\", \"REFERENCE\" (case-sensitive), or \"first_frame\".","commonSituations":"Guessing role names; case mismatch; using another model's role vocabulary.","solutions":["Use the exact lowercase strings 'keyframe' or 'reference'","Import the role constants rather than hardcoding"],"exampleFix":"// before\n{\"role\": \"REFERENCE\", ...}\n// after\n{\"role\": \"reference\", ...}","handlingStrategy":"type-guard","validationCode":"if cond['role'] not in ('keyframe', 'reference'):\n    raise ValueError('bad role')","typeGuard":"def is_valid_role(v: str) -> bool:\n    return v in ('keyframe', 'reference')","tryCatchPattern":null,"preventionTips":["Import role constants instead of hardcoding strings"],"tags":["minimax-h3","conditions","role","enum-validation"],"backgroundTag":"value-not-in-allowed-set","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}