{"record":{"id":"8a3c7ea4fdb3d7ee","repo":"sgl-project/sglang","slug":"fl2va-keyframe-preparation-requires-cached-pre-que","errorCode":null,"errorMessage":"fl2va keyframe preparation requires cached pre-queue probe and shape facts for conditions[{condition_index}]","messagePattern":"fl2va keyframe preparation requires cached pre-queue probe and shape facts for conditions\\[(.+?)\\]","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/canvas.py","lineNumber":183,"sourceCode":"    from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.prequeue import (\n        MINIMAX_H3_PROBE_FACTS_EXTRA_KEY,\n        MINIMAX_H3_RESOLVED_MATERIAL_SHAPES_EXTRA_KEY,\n    )\n\n    probe_facts = batch.extra.get(MINIMAX_H3_PROBE_FACTS_EXTRA_KEY)\n    material_shapes = batch.extra.get(MINIMAX_H3_RESOLVED_MATERIAL_SHAPES_EXTRA_KEY)\n    for material in keyframes:\n        condition_index = int(material.condition_index)\n        facts = (\n            probe_facts.get(condition_index) if isinstance(probe_facts, dict) else None\n        )\n        material_shape = (\n            material_shapes.get(condition_index)\n            if isinstance(material_shapes, dict)\n            else None\n        )\n        if not isinstance(facts, dict) or not isinstance(material_shape, dict):\n            raise ValueError(\n                \"fl2va keyframe preparation requires cached pre-queue probe and \"\n                f\"shape facts for conditions[{condition_index}]\"\n            )\n        if (\n            int(material_shape.get(\"width\") or 0),\n            int(material_shape.get(\"height\") or 0),\n        ) != (canvas_w, canvas_h):\n            raise ValueError(\n                \"fl2va keyframe material shape disagrees with the resolved target: \"\n                f\"condition={condition_index}, material=\"\n                f\"{material_shape.get('width')}x{material_shape.get('height')}, \"\n                f\"target={canvas_w}x{canvas_h}\"\n            )\n\n    from PIL import Image, ImageOps\n\n    from sglang.multimodal_gen.runtime.pipelines_core.stages.model_specific_stages.minimax_h3.material_io import (\n        minimax_h3_localize_material_uri,","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/canvas.py#L165-L201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the pre-queue probe stage before keyframe preparation so both facts dicts are populated","Ensure material_shapes is a dict with an entry for every condition_index in the plan","Validate the fl2va extras structure right after the probe stage and fail fast there"],"exampleFix":"// before\nresult = minimax_h3_prepared_keyframes(plan, keyframes, batch)  # probe stage skipped\n// after\nbatch = run_prequeue_probe_stage(batch)  # populates probe + shape facts\nresult = minimax_h3_prepared_keyframes(plan, keyframes, batch)","handlingStrategy":"validation","validationCode":"for i, cond in enumerate(plan.conditions):\n    facts = probe_facts.get(i)\n    shape = material_shapes.get(i) if isinstance(material_shapes, dict) else None\n    if not isinstance(facts, dict) or not isinstance(shape, dict):\n        raise RuntimeError(f'run the pre-queue probe for condition {i} first')","typeGuard":"def fl2va_facts_ready(probe_facts, material_shapes, condition_index) -> bool:\n    return isinstance(probe_facts.get(condition_index), dict) and isinstance(\n        (material_shapes or {}).get(condition_index), dict)","tryCatchPattern":null,"preventionTips":["Always run the pre-queue probe stage first in fl2va pipelines","Assert extras structure between stages in dev builds"],"tags":["minimax-h3","fl2va","pipeline-ordering","missing-metadata"],"backgroundTag":"missing-prerequisite-stage-data","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}