{"record":{"id":"e59d2485b40387ab","repo":"sgl-project/sglang","slug":"invalid-forward-mode-forward-batch-forward-mode","errorCode":null,"errorMessage":"Invalid forward mode: {forward_batch.forward_mode=}","messagePattern":"Invalid forward mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/layers/attention/hybrid_linear_attn_backend.py","lineNumber":244,"sourceCode":"                )\n                query_start_loc[:bs] = forward_batch.extend_start_loc\n                query_start_loc[bs] = (\n                    forward_batch.extend_start_loc[-1]\n                    + forward_batch.extend_seq_lens[-1]\n                )\n                if has_mamba_track_mask:\n                    track_conv_indices = self._init_track_conv_indices(\n                        query_start_loc, forward_batch\n                    )\n\n                    (\n                        track_ssm_h_src,\n                        track_ssm_h_dst,\n                        track_ssm_final_src,\n                        track_ssm_final_dst,\n                    ) = self._init_track_ssm_indices(mamba_cache_indices, forward_batch)\n        else:\n            raise ValueError(f\"Invalid forward mode: {forward_batch.forward_mode=}\")\n\n        return ForwardMetadata(\n            query_start_loc=query_start_loc,\n            mamba_cache_indices=mamba_cache_indices,\n            # Physical track destinations (None when tracking off); cuda-graph\n            # supplies this via the static backend buffer in _replay_metadata.\n            mamba_track_indices=getattr(forward_batch, \"mamba_track_indices\", None),\n            retrieve_next_token=retrieve_next_token,\n            retrieve_next_sibling=retrieve_next_sibling,\n            retrieve_parent_token=retrieve_parent_token,\n            track_conv_indices=track_conv_indices,\n            track_ssm_h_src=track_ssm_h_src,\n            track_ssm_h_dst=track_ssm_h_dst,\n            track_ssm_final_src=track_ssm_final_src,\n            track_ssm_final_dst=track_ssm_final_dst,\n            has_mamba_track_mask=has_mamba_track_mask,\n            replayssm_write_pos=replayssm_write_pos,\n            replayssm_force_flush=replayssm_force_flush,","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/layers/attention/hybrid_linear_attn_backend.py#L226-L262","documentation":"HybridLinearAttnBackend._forward_metadata builds per-mode metadata (SSM/mamba indices, query layouts, tracking buffers) and only handles the forward modes it knows (extend, decode, idle, and speculative modes). If forward_batch.forward_mode is anything else, it raises this ValueError to fail fast instead of building garbage metadata.","triggerScenarios":"Calling init_forward_metadata on HybridLinearAttnBackend with a ForwardMode not covered by its if/elif chain — e.g. a newly added ForwardMode enum value (new speculative/draft mode) or a custom forward mode passed via a ForwardBatch.","commonSituations":"Adding a new forward mode to sglang (e.g. a new speculative decoding strategy or draft extension mode) without updating the hybrid linear (mamba/GDN) backend; or a version mismatch where the backend lags the core ForwardMode enum.","solutions":["Check ForwardBatch.forward_mode before dispatching; route only supported modes (EXTEND/DECODE/idle/speculative) to HybridLinearAttnBackend","If you added a new ForwardMode, extend the if/elif chain in _forward_metadata to handle it","Upgrade/downgrade sglang so backend and ForwardMode enum are in sync"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"SUPPORTED = {ForwardMode.EXTEND, ForwardMode.DECODE, ForwardMode.IDLE,\n              ForwardMode.TARGET_VERIFY, ForwardMode.DRAFT}\nassert forward_batch.forward_mode in SUPPORTED, forward_batch.forward_mode","typeGuard":"def backend_handles_mode(mode: ForwardMode) -> bool:\n    return mode in {ForwardMode.EXTEND, ForwardMode.DECODE, ForwardMode.IDLE,\n                    ForwardMode.TARGET_VERIFY, ForwardMode.DRAFT}","tryCatchPattern":"try:\n    backend.init_forward_metadata(...)\nexcept ValueError as e:\n    if 'Invalid forward mode' in str(e):\n        raise UnsupportedModeForHybridBackend(forward_batch.forward_mode) from e\n    raise","preventionTips":["Gate new ForwardMode additions with backend-compatibility tests for hybrid/mamba models","Run hybrid model smoke tests in CI for every new decoding mode","Check backend mode coverage before enabling experimental speculative modes"],"tags":["forward-mode","hybrid-linear-attention","mamba","metadata","sglang"],"backgroundTag":"unhandled-enum-value-dispatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}