{"record":{"id":"dec6a59d8e06253d","repo":"sgl-project/sglang","slug":"ref2va-video-preparation-requires-a-video-or-video","errorCode":null,"errorMessage":"ref2va video preparation requires a video or video_audio reference","messagePattern":"ref2va video preparation requires a video or video_audio reference","errorType":"validation","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py","lineNumber":776,"sourceCode":"    *,\n    share_across_replicas: bool = False,\n) -> dict[str, Any]:\n    \"\"\"Decode the bounded reference-video RGB frames once per request.\n\n    BOTH the visual-condition tokenizer and Qwen consume the same transformed\n    array. Its frame cap comes from the resolved target duration (17n+5 rule).\n    The original path travels alongside for direct soundtrack decoding.\n    \"\"\"\n    from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.constants import (\n        MINIMAX_H3_PREPARED_REFERENCE_VIDEO_EXTRA_KEY,\n    )\n\n    cached = batch.extra.get(MINIMAX_H3_PREPARED_REFERENCE_VIDEO_EXTRA_KEY)\n    if cached is not None:\n        return cached\n    videos = _reference_video_materials(plan)\n    if not videos:\n        raise NotImplementedError(\n            \"ref2va video preparation requires a video or video_audio reference\"\n        )\n\n    prepared_videos = []\n    for material in videos:\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.material_io import (\n            minimax_h3_localize_material_uri,\n        )\n\n        video_path = minimax_h3_localize_material_uri(\n            batch,\n            material.uri,\n            condition_type=material.condition_type,\n            condition_index=int(material.condition_index),\n        )\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.prequeue import (\n            MINIMAX_H3_PROBE_FACTS_EXTRA_KEY,\n            MINIMAX_H3_RESOLVED_MATERIAL_SHAPES_EXTRA_KEY,","sourceCodeStart":758,"sourceCodeEnd":794,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py#L758-L794","documentation":"The ref2va video preparation path requires a 'video' or 'video_audio' reference material; with none present it raises NotImplementedError (deliberately: video conditioning is mandatory on this path, not merely unsupported yet).","triggerScenarios":"Calling _encode_ref2va or _encode_reference_video on a plan whose materials contain no video or video_audio reference materials.","commonSituations":"Image-only requests sent to the ref2va video path, or a material classifier routing video uploads into the wrong chain.","solutions":["Attach a video (or video_audio) reference material to the request","For image-only generation, use the path/partition that doesn't require video conditioning","Fix material_chain assignment upstream if videos are being misclassified"],"exampleFix":"// before\n_encode_ref2va(plan_without_video)\n\n// after\n_encode_ref2va(plan_with_video_reference)","handlingStrategy":"validation","validationCode":"def has_video_reference(plan) -> bool:\n    return any(m.material_chain in (\"video.reference_preserve\", \"video_audio.reference_preserve\") for m in plan.materials)","typeGuard":"def has_video_reference(plan) -> bool:\n    return any(m.material_chain in (\"video.reference_preserve\", \"video_audio.reference_preserve\") for m in plan.materials)","tryCatchPattern":"try:\n    minimax_h3_prepared_reference_videos(batch, plan)\nexcept NotImplementedError as e:\n    if 'video or video_audio' in str(e):\n        return bad_request(e)\n    raise","preventionTips":["Require a video material for ref2va video conditioning","Log plan.materials chains on ingest to catch misclassification"],"tags":["minimax-h3","ref2va","missing-input","not-implemented"],"backgroundTag":"missing-required-input","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}