{"record":{"id":"37a1d0b2ef033985","repo":"sgl-project/sglang","slug":"unsupported-capture-mode-mode","errorCode":null,"errorMessage":"unsupported capture mode: {mode}","messagePattern":"unsupported capture mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/sana_wm/streaming_refiner.py","lineNumber":64,"sourceCode":"        return\n    for block, prefix in zip(transformer.transformer_blocks, kv_prefix_per_layer):\n        block.attn1._tf_kv_prefix = prefix\n\n\ndef clear_kv_prefix_on_blocks(transformer: nn.Module) -> None:\n    for block in transformer.transformer_blocks:\n        block.attn1._tf_kv_prefix = None\n\n\ndef set_capture_flag_on_blocks(\n    transformer: nn.Module, mode: str, *, enable: bool\n) -> None:\n    if mode == \"pre_rope\":\n        attr, clear_attr = \"_kv_cache_capture\", \"_cached_kv_pre\"\n    elif mode == \"post_rope\":\n        attr, clear_attr = \"_tf_capture_kv\", \"_cached_kv_post\"\n    else:\n        raise ValueError(f\"unsupported capture mode: {mode}\")\n    for block in transformer.transformer_blocks:\n        setattr(block.attn1, attr, bool(enable))\n        if enable and hasattr(block.attn1, clear_attr):\n            setattr(block.attn1, clear_attr, None)\n\n\ndef collect_captured_kv_from_blocks(transformer: nn.Module, mode: str):\n    attr = \"_cached_kv_pre\" if mode == \"pre_rope\" else \"_cached_kv_post\"\n    out = []\n    for block in transformer.transformer_blocks:\n        cached = getattr(block.attn1, attr, None)\n        if cached is None:\n            raise RuntimeError(f\"missing captured KV on {attr}\")\n        out.append(cached)\n        setattr(block.attn1, attr, None)\n    return out\n\n","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/sana_wm/streaming_refiner.py#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"Extending the streaming-refiner KV capture with a new capture point and passing an unregistered mode name; string typos in caller code.","solutions":["Use exactly 'pre_rope' or 'post_rope'","If adding a new capture point, extend the if/elif chain in this function first"],"exampleFix":"# before\nset_capture_flag_on_blocks(tf, mode=\"pre\")\n# after\nset_capture_flag_on_blocks(tf, mode=\"pre_rope\")","handlingStrategy":"validation","validationCode":"assert mode in (\"pre_rope\", \"post_rope\"), mode","typeGuard":"def is_capture_mode(mode: str) -> bool:\n    return mode in (\"pre_rope\", \"post_rope\")","tryCatchPattern":"null","preventionTips":["Use module-level constants for capture mode names","Lint caller sites when adding new modes","Keep enable/collect call sites adjacent in code"],"tags":["sana-wm","streaming-refiner","kv-capture","mode-string","valueerror"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}