sgl-project/sglang · error · ValueError

cached keyframe preparation disagrees with the resolved plan

Error message

cached keyframe preparation disagrees with the resolved plan

What it means

The stage found a previously computed keyframe preparation cached under MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY in batch.extra, but its semantic_frame_indices or image count does not match the freshly validated plan. This protects against serving a stale cache entry that would encode keyframes inconsistent with the current request plan.

Source

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


def minimax_h3_prepared_keyframes(batch: Any, plan: Any) -> dict[str, Any]:
    """Resolve + prepare one or two first/last keyframes once per request.

    The target canvas is shared across keyframes and must already be frozen by
    the pre-queue probe/resolve hook.
    Top-level ``image`` / ``canvas_width`` / ``canvas_height`` keys mirror the
    first-keyframe payload for compatibility; per-keyframe entries live under
    ``images``.
    """
    keyframes = _keyframe_materials(plan)
    semantic_indices = _validate_keyframe_materials(plan, keyframes)
    cached = batch.extra.get(MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY)
    if cached is not None:
        cached_indices = tuple(cached.get("semantic_frame_indices") or ())
        cached_images = cached.get("images") or ()
        if cached_indices != semantic_indices or len(cached_images) != len(keyframes):
            raise ValueError(
                "cached keyframe preparation disagrees with the resolved plan"
            )
        return cached

    canvas_w, canvas_h = _keyframe_canvas_size(plan.shape)

    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
        )

View on GitHub (pinned to 0132848349)

Solutions

Clear/invalidate the MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY entry in batch.extra whenever the plan or keyframe list changes
Make the cache key content-addressed (hash of semantic_indices + image count) instead of reusing the extra slot blindly
If regenerating materials, remove the cached dict before calling minimax_h3_prepared_keyframes

Example fix

// before
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)  # batch.extra holds stale cache
// after
batch.extra.pop(MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY, None)
result = minimax_h3_prepared_keyframes(plan, keyframes, batch)

Defensive patterns

Strategy: validation

Validate before calling

cached = batch.extra.get(MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY)
if cached is not None:
    if tuple(cached.get('semantic_frame_indices') or ()) != semantic_indices or len(cached.get('images') or ()) != len(keyframes):
        del batch.extra[MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY]

Type guard

def cache_is_fresh(cached, semantic_indices, n) -> bool:
    return (tuple(cached.get('semantic_frame_indices') or ()) == tuple(semantic_indices)
            and len(cached.get('images') or ()) == n)

Try / catch

try:
    result = minimax_h3_prepared_keyframes(plan, keyframes, batch)
except ValueError as e:
    if 'cached keyframe preparation' in str(e):
        batch.extra.pop(MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY, None)
        result = minimax_h3_prepared_keyframes(plan, keyframes, batch)
    else:
        raise

Prevention

Invalidate the extra-key cache on any plan mutation
Key caches by plan content, not batch identity

When it happens

Trigger: batch.extra carries a MINIMAX_H3_PREPARED_KEYFRAMES_EXTRA_KEY entry from an earlier run while the plan's semantic_indices or keyframes list length changed between runs within the same batch object.

Common situations: Retrying or re-running a pipeline stage on the same batch after modifying the plan, sharing batch objects across pipeline variants, or a caching layer that keys only on batch identity rather than plan content.

Related errors

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