sgl-project/sglang · error · ValueError

fl2va keyframe preparation requires cached pre-queue probe a

Error message

fl2va keyframe preparation requires cached pre-queue probe and shape facts for conditions[{condition_index}]

What it means

For fl2va conditions, keyframe preparation depends on a cached pre-queue probe result and per-condition material shape facts, both expected as dicts in batch extras. The error reports that for conditions[condition_index] either the probe facts or the material_shape entry is missing or not a dict, so canvas geometry cannot be validated.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/canvas.py:183

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

    probe_facts = batch.extra.get(MINIMAX_H3_PROBE_FACTS_EXTRA_KEY)
    material_shapes = batch.extra.get(MINIMAX_H3_RESOLVED_MATERIAL_SHAPES_EXTRA_KEY)
    for material in keyframes:
        condition_index = int(material.condition_index)
        facts = (
            probe_facts.get(condition_index) if isinstance(probe_facts, dict) else None
        )
        material_shape = (
            material_shapes.get(condition_index)
            if isinstance(material_shapes, dict)
            else None
        )
        if not isinstance(facts, dict) or not isinstance(material_shape, dict):
            raise ValueError(
                "fl2va keyframe preparation requires cached pre-queue probe and "
                f"shape facts for conditions[{condition_index}]"
            )
        if (
            int(material_shape.get("width") or 0),
            int(material_shape.get("height") or 0),
        ) != (canvas_w, canvas_h):
            raise ValueError(
                "fl2va keyframe material shape disagrees with the resolved target: "
                f"condition={condition_index}, material="
                f"{material_shape.get('width')}x{material_shape.get('height')}, "
                f"target={canvas_w}x{canvas_h}"
            )

    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,

View on GitHub (pinned to 0132848349)

Solutions

1. Run the pre-queue probe stage before keyframe preparation so both facts dicts are populated
2. Ensure material_shapes is a dict with an entry for every condition_index in the plan
3. Validate the fl2va extras structure right after the probe stage and fail fast there

Example fix

// before
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)  # probe stage skipped
// after
batch = run_prequeue_probe_stage(batch)  # populates probe + shape facts
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)

for i, cond in enumerate(plan.conditions):
    facts = probe_facts.get(i)
    shape = material_shapes.get(i) if isinstance(material_shapes, dict) else None
    if not isinstance(facts, dict) or not isinstance(shape, dict):
        raise RuntimeError(f'run the pre-queue probe for condition {i} first')

def fl2va_facts_ready(probe_facts, material_shapes, condition_index) -> bool:
    return isinstance(probe_facts.get(condition_index), dict) and isinstance(
        (material_shapes or {}).get(condition_index), dict)

When it happens

Trigger: Calling minimax_h3_prepared_keyframes on an fl2va plan when the pre-queue probe stage never ran, its facts were stored under a different key/type, or material_shapes (dict keyed by condition index) lacks an entry for condition_index.

Common situations: Skipping the pre-queue probe stage in a custom pipeline, reordering stages so keyframe preparation runs before probing, or condition indices shifting after editing the plan without refreshing material_shapes.

Related errors

• conditions for task {task!r} must include one or two ordered
• fl2va denoising requires encoded keyframe condition rows
• MiniMax H3 text encoding requires an ordered keyframe signat
• fl2va Qwen preparation requires one or two ordered images wi
• keyframe visual preparation requires one or two ordered imag

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