sgl-project/sglang · error · ValueError

unsupported capture mode: {mode}

Error message

unsupported capture mode: {mode}

What it means

set_capture_flag_on_blocks enables KV-capture on transformer attention blocks for exactly two modes: 'pre_rope' (attr _kv_cache_capture, cache _cached_kv_pre) and 'post_rope' (attr _tf_capture_kv, cache _cached_kv_post). Any other mode string raises this ValueError.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/sana_wm/streaming_refiner.py:64

        return
    for block, prefix in zip(transformer.transformer_blocks, kv_prefix_per_layer):
        block.attn1._tf_kv_prefix = prefix


def clear_kv_prefix_on_blocks(transformer: nn.Module) -> None:
    for block in transformer.transformer_blocks:
        block.attn1._tf_kv_prefix = None


def set_capture_flag_on_blocks(
    transformer: nn.Module, mode: str, *, enable: bool
) -> None:
    if mode == "pre_rope":
        attr, clear_attr = "_kv_cache_capture", "_cached_kv_pre"
    elif mode == "post_rope":
        attr, clear_attr = "_tf_capture_kv", "_cached_kv_post"
    else:
        raise ValueError(f"unsupported capture mode: {mode}")
    for block in transformer.transformer_blocks:
        setattr(block.attn1, attr, bool(enable))
        if enable and hasattr(block.attn1, clear_attr):
            setattr(block.attn1, clear_attr, None)


def collect_captured_kv_from_blocks(transformer: nn.Module, mode: str):
    attr = "_cached_kv_pre" if mode == "pre_rope" else "_cached_kv_post"
    out = []
    for block in transformer.transformer_blocks:
        cached = getattr(block.attn1, attr, None)
        if cached is None:
            raise RuntimeError(f"missing captured KV on {attr}")
        out.append(cached)
        setattr(block.attn1, attr, None)
    return out

View on GitHub (pinned to 0132848349)

Solutions

1. Use exactly 'pre_rope' or 'post_rope'
2. If adding a new capture point, extend the if/elif chain in this function first

Example fix

# before
set_capture_flag_on_blocks(tf, mode="pre")
# after
set_capture_flag_on_blocks(tf, mode="pre_rope")

assert mode in ("pre_rope", "post_rope"), mode

def is_capture_mode(mode: str) -> bool:
    return mode in ("pre_rope", "post_rope")

null

When it happens

Trigger: Calling set_capture_flag_on_blocks(transformer, mode='pre') or any typo/variant like 'post-rope', 'raw', or a mode constant copied from another codebase.

Common situations: Extending the streaming-refiner KV capture with a new capture point and passing an unregistered mode name; string typos in caller code.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• missing captured KV on {attr}
• SANA-WM refiner requires a string prompt or one prompt per b
• Stage-1 latent has {z.shape[2]} frames but sink_size={sink_s
• SANA-WM refiner requires batch.latents from stage 1.
• SANA-WM refiner expects 5D latents shaped (B, C, T, H, W), g

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