sgl-project/sglang · error · ValueError

prepared reference videos payload must carry a non-empty 'vi

Error message

prepared reference videos payload must carry a non-empty 'videos' list, got {videos!r}

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/stages/visual_encoding.py:296

        """ref2va video/video_audio encode from shared transformed frames."""
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.constants import (
            MINIMAX_H3_REFERENCE_VIDEO_ROWS_EXTRA_KEY,
        )
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.reference_encoding import (
            minimax_h3_encode_reference_video_rows,
            minimax_h3_prepared_reference_videos,
        )

        if MINIMAX_H3_REFERENCE_VIDEO_ROWS_EXTRA_KEY in batch.extra:
            return
        prepared = minimax_h3_prepared_reference_videos(
            batch,
            plan,
            share_across_replicas=bool(self.video_vae.parallel_tiling),
        )
        videos = prepared.get("videos")
        if not isinstance(videos, list) or not videos:
            raise ValueError(
                "prepared reference videos payload must carry a non-empty "
                f"'videos' list, got {videos!r}"
            )
        entries = []
        for item in videos:
            rows, latent_t, latent_h, latent_w = minimax_h3_encode_reference_video_rows(
                self.video_vae,
                item["frames"],
                self.vae_arch_config,
            )
            entries.append(
                {
                    "rows": rows,
                    "latent_t": latent_t,
                    "latent_h": latent_h,
                    "latent_w": latent_w,
                    "condition_index": int(item["condition_index"]),
                    "material_chain": str(item["material_chain"]),

View on GitHub (pinned to 0132848349)

Solutions

1. Attach at least one valid reference video to the ref2va request
2. Inspect the dict returned by minimax_h3_prepared_reference_videos to confirm the 'videos' key exists and is a non-empty list
3. Check upstream filters/codec validation that may have silently dropped the video

Example fix

// before
request["reference"] = {"video_urls": []}

// after
request["reference"] = {"video_urls": ["gs://bucket/ref.mp4"]}

prepared = minimax_h3_prepared_reference_videos(batch, plan)
videos = prepared.get("videos")
if not isinstance(videos, list) or not videos:
    raise ValueError("reference video missing; attach one before running ref2va")

def has_reference_video(prepared: dict) -> bool:
    return isinstance(prepared.get("videos"), list) and len(prepared["videos"]) > 0

catch ValueError and check the message for "videos' list" to branch to a 'missing reference video' user error

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• {context}video block token counts and timestamps must align
• {name} must be an int or a sequence of ints
• video block token counts and timestamps must align
• image_token_count required for an image reference
• video reference requires block token counts and timestamps

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