sgl-project/sglang · error · NotImplementedError

ref2va video preparation requires a video or video_audio ref

Error message

ref2va video preparation requires a video or video_audio reference

What it means

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

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py:776

    *,
    share_across_replicas: bool = False,
) -> dict[str, Any]:
    """Decode the bounded reference-video RGB frames once per request.

    BOTH the visual-condition tokenizer and Qwen consume the same transformed
    array. Its frame cap comes from the resolved target duration (17n+5 rule).
    The original path travels alongside for direct soundtrack decoding.
    """
    from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.constants import (
        MINIMAX_H3_PREPARED_REFERENCE_VIDEO_EXTRA_KEY,
    )

    cached = batch.extra.get(MINIMAX_H3_PREPARED_REFERENCE_VIDEO_EXTRA_KEY)
    if cached is not None:
        return cached
    videos = _reference_video_materials(plan)
    if not videos:
        raise NotImplementedError(
            "ref2va video preparation requires a video or video_audio reference"
        )

    prepared_videos = []
    for material in videos:
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.material_io import (
            minimax_h3_localize_material_uri,
        )

        video_path = minimax_h3_localize_material_uri(
            batch,
            material.uri,
            condition_type=material.condition_type,
            condition_index=int(material.condition_index),
        )
        from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.prequeue import (
            MINIMAX_H3_PROBE_FACTS_EXTRA_KEY,
            MINIMAX_H3_RESOLVED_MATERIAL_SHAPES_EXTRA_KEY,

View on GitHub (pinned to 0132848349)

Solutions

  1. Attach a video (or video_audio) reference material to the request
  2. For image-only generation, use the path/partition that doesn't require video conditioning
  3. Fix material_chain assignment upstream if videos are being misclassified

Example fix

// before
_encode_ref2va(plan_without_video)

// after
_encode_ref2va(plan_with_video_reference)
Defensive patterns

Strategy: validation

Validate before calling

def has_video_reference(plan) -> bool:
    return any(m.material_chain in ("video.reference_preserve", "video_audio.reference_preserve") for m in plan.materials)

Type guard

def has_video_reference(plan) -> bool:
    return any(m.material_chain in ("video.reference_preserve", "video_audio.reference_preserve") for m in plan.materials)

Try / catch

try:
    minimax_h3_prepared_reference_videos(batch, plan)
except NotImplementedError as e:
    if 'video or video_audio' in str(e):
        return bad_request(e)
    raise

Prevention

When it happens

Trigger: Calling _encode_ref2va or _encode_reference_video on a plan whose materials contain no video or video_audio reference materials.

Common situations: Image-only requests sent to the ref2va video path, or a material classifier routing video uploads into the wrong chain.

Related errors

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