{"record":{"id":"9988dae75c7fe637","repo":"sgl-project/sglang","slug":"prepared-reference-videos-payload-must-carry-a-non","errorCode":null,"errorMessage":"prepared reference videos payload must carry a non-empty 'videos' list, got {videos!r}","messagePattern":"prepared reference videos payload must carry a non-empty 'videos' list, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py","lineNumber":296,"sourceCode":"        \"\"\"ref2va video/video_audio encode from shared transformed frames.\"\"\"\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.constants import (\n            MINIMAX_H3_REFERENCE_VIDEO_ROWS_EXTRA_KEY,\n        )\n        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.reference_encoding import (\n            minimax_h3_encode_reference_video_rows,\n            minimax_h3_prepared_reference_videos,\n        )\n\n        if MINIMAX_H3_REFERENCE_VIDEO_ROWS_EXTRA_KEY in batch.extra:\n            return\n        prepared = minimax_h3_prepared_reference_videos(\n            batch,\n            plan,\n            share_across_replicas=bool(self.video_vae.parallel_tiling),\n        )\n        videos = prepared.get(\"videos\")\n        if not isinstance(videos, list) or not videos:\n            raise ValueError(\n                \"prepared reference videos payload must carry a non-empty \"\n                f\"'videos' list, got {videos!r}\"\n            )\n        entries = []\n        for item in videos:\n            rows, latent_t, latent_h, latent_w = minimax_h3_encode_reference_video_rows(\n                self.video_vae,\n                item[\"frames\"],\n                self.vae_arch_config,\n            )\n            entries.append(\n                {\n                    \"rows\": rows,\n                    \"latent_t\": latent_t,\n                    \"latent_h\": latent_h,\n                    \"latent_w\": latent_w,\n                    \"condition_index\": int(item[\"condition_index\"]),\n                    \"material_chain\": str(item[\"material_chain\"]),","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py#L278-L314","documentation":"The reference-video encoding path expects the prepared payload (from minimax_h3_prepared_reference_videos) to contain a non-empty list under the 'videos' key. If 'videos' is missing, None, not a list, or an empty list, the stage refuses to continue because there is nothing to encode for a ref2va request.","triggerScenarios":"Running a ref2va task where the preparation step produced no videos: request has no reference video attached, the payload uses a wrong key, or preparation filtered out all videos (e.g. unsupported video format).","commonSituations":"Forgetting to attach the reference video in the request; key mismatch after payload schema changes; upstream filtering dropping the only video due to codec/geometry validation; calling reference-video encoding from a plan that didn't include the video condition.","solutions":["Attach at least one valid reference video to the ref2va request","Inspect the dict returned by minimax_h3_prepared_reference_videos to confirm the 'videos' key exists and is a non-empty list","Check upstream filters/codec validation that may have silently dropped the video"],"exampleFix":"// before\nrequest[\"reference\"] = {\"video_urls\": []}\n\n// after\nrequest[\"reference\"] = {\"video_urls\": [\"gs://bucket/ref.mp4\"]}","handlingStrategy":"validation","validationCode":"prepared = minimax_h3_prepared_reference_videos(batch, plan)\nvideos = prepared.get(\"videos\")\nif not isinstance(videos, list) or not videos:\n    raise ValueError(\"reference video missing; attach one before running ref2va\")","typeGuard":"def has_reference_video(prepared: dict) -> bool:\n    return isinstance(prepared.get(\"videos\"), list) and len(prepared[\"videos\"]) > 0","tryCatchPattern":"catch ValueError and check the message for \"videos' list\" to branch to a 'missing reference video' user error","preventionTips":["Require a non-empty video URL list for ref2va in request validation","Verify video files exist and are readable before submission"],"tags":["minimax-h3","ref2va","reference-video","payload-validation"],"backgroundTag":"missing-required-field","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}