sgl-project/sglang · error · ValueError

ref2va requires at least one image reference

Error message

ref2va requires at least one image reference

What it means

The ref2va partition requires at least one material with material_chain == 'image.reference_preserve' to build its reference image conditioning. If the plan contains none, minimax_h3_prepared_reference_image refuses to proceed.

Source

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

    batch.extra[MINIMAX_H3_PREPARED_REFERENCE_VIDEO_EXTRA_KEY] = prepared
    return prepared


def minimax_h3_prepared_reference_image(batch: Any, plan: Any) -> dict[str, Any]:
    """Resize ref2va image references to their pre-queue-resolved shapes.

    Qwen (pixel_values) and the visual-condition tokenizer consume the identical
    prepared image. The runtime never recomputes geometry from ``plan.shape``;
    it consumes the per-material width/height admitted before queueing.
    """
    cached = batch.extra.get(MINIMAX_H3_PREPARED_REFERENCE_IMAGE_EXTRA_KEY)
    if cached is not None:
        return cached
    images = [
        m for m in plan.materials if m.material_chain == "image.reference_preserve"
    ]
    if not images:
        raise ValueError("ref2va requires at least one image reference")
    from PIL import Image, ImageOps

    from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.material_io import (
        minimax_h3_localize_material_uri,
    )

    prepared_images = []
    for material in images:
        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,
        )

        condition_index = int(material.condition_index)
        source_facts = batch.extra.get(MINIMAX_H3_PROBE_FACTS_EXTRA_KEY, {}).get(
            condition_index
        )
        resolved_shape = batch.extra.get(

View on GitHub (pinned to 0132848349)

Solutions

1. Attach at least one image reference (material_chain 'image.reference_preserve') to the request
2. Route text-only or no-image requests to the fl2va partition instead
3. Validate request shape against the loaded partition's declared tasks/materials before enqueueing

Example fix

// before
request(materials=[video_material])  # ref2va -> ValueError

// after
request(materials=[image_material, video_material])

def ref2va_ready(plan) -> bool:
    return any(m.material_chain == "image.reference_preserve" for m in plan.materials)

def has_image_reference(plan) -> bool:
    return any(m.material_chain == "image.reference_preserve" for m in plan.materials)

When it happens

Trigger: Sending a request to the ref2va model with no image reference attached (text-only, or only audio/video materials), reaching _encode_ref2va/_encode_reference_image.

Common situations: Users assuming image references are optional for the reference-preserving model, or a client dropping the image attachment on serialization.

Related errors

• ref2va video preparation requires a video or video_audio ref
• {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

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