{"record":{"id":"12f769e13fc97f9a","repo":"sgl-project/sglang","slug":"enable-linear-replayssm-spec-requires-a-linear-d","errorCode":null,"errorMessage":"--enable-linear-replayssm-spec requires a linear draft chain (--speculative-eagle-topk in {None, 1}); the chunked verify kernel uses a strictly-lower causal mask and is invalid for EAGLE tree verify. Got --speculative-eagle-topk={cfg.speculative_eagle_topk!r}.","messagePattern":"--enable-linear-replayssm-spec requires a linear draft chain \\(--speculative-eagle-topk in (.+?)\\); the chunked verify kernel uses a strictly-lower causal mask and is invalid for EAGLE tree verify\\. Got --speculative-eagle-topk=(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":6979,"sourceCode":"            if cfg.linear_replayssm_cache_len < 1:\n                raise ValueError(\n                    \"--linear-replayssm-cache-len must be >= 1, got \"\n                    f\"{cfg.linear_replayssm_cache_len}.\"\n                )\n\n        # ReplaySSM spec-verify (Part B of #28511): linear-chain target verify via\n        # fold-every-commit -- the verify stores each draft step's raw inputs into\n        # the per-slot (rawv, rawk, g, beta) window and the commit replays the\n        # accepted prefix into the fp32 checkpoint. The intra-window interaction\n        # uses a strictly-lower causal mask, so it is valid ONLY for a linear\n        # draft chain (speculative_eagle_topk in {None, 1}, i.e. NEXTN / MTP);\n        # EAGLE tree verify (topk > 1) must fall back to the recurrent verify.\n        # GDN sizes the window to the draft maximum; KDA (kda_backend) keeps a\n        # --linear-replayssm-cache-len window and folds via its own fused\n        # verify ring-write + commit_kda_replayssm_after_verify.\n        if cfg.enable_linear_replayssm_spec:\n            if cfg.speculative_eagle_topk not in (None, 1):\n                raise ValueError(\n                    \"--enable-linear-replayssm-spec requires a linear draft chain \"\n                    \"(--speculative-eagle-topk in {None, 1}); the chunked verify \"\n                    \"kernel uses a strictly-lower causal mask and is invalid for \"\n                    \"EAGLE tree verify. Got \"\n                    f\"--speculative-eagle-topk={cfg.speculative_eagle_topk!r}.\"\n                )\n            if decode not in (\"triton\", \"flashinfer\"):\n                raise ValueError(\n                    \"--enable-linear-replayssm-spec requires the triton or \"\n                    \"flashinfer linear-attn decode backend, got \"\n                    f\"--linear-attn-decode-backend={decode!r}.\"\n                )\n            from sglang.srt.speculative.ragged_verify import (\n                RaggedVerifyMode,\n                read_ragged_verify_mode,\n            )\n\n            ragged_mode = read_ragged_verify_mode()","sourceCodeStart":6961,"sourceCodeEnd":6997,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L6961-L6997","documentation":"ReplaySSM spec-verify (--enable-linear-replayssm-spec) only supports a linear draft chain, i.e. --speculative-eagle-topk in {None, 1}. The chunked verify kernel uses a strictly-lower causal mask, which is invalid for EAGLE tree verification with topk > 1; tree topologies must fall back to the recurrent verify.","triggerScenarios":"--enable-linear-replayssm-spec with --speculative-eagle-topk 2+ (EAGLE tree drafting) on a hybrid linear-attention model.","commonSituations":"Reusing an EAGLE topk>1 spec-decode config from a full-attention model when enabling ReplaySSM spec on GDN/KDA hybrids; not realizing the spec path is chain-only.","solutions":["Set --speculative-eagle-topk 1 (linear chain) or remove the flag","Or disable --enable-linear-replayssm-spec and use the recurrent verify path for tree drafting"],"exampleFix":"# before\n--enable-linear-replayssm-spec --speculative-eagle-topk 4\n# after\n--enable-linear-replayssm-spec --speculative-eagle-topk 1","handlingStrategy":"validation","validationCode":"def validate(topk, enable_spec):\n    return not enable_spec or topk in (None, 1)","typeGuard":"def is_linear_chain(topk) -> bool: return topk in (None, 1)","tryCatchPattern":null,"preventionTips":["Don't reuse EAGLE tree configs with ReplaySSM spec","Read flag docs for speculative constraints before combining"],"tags":["sglang","replayssm","speculative-decoding","eagle","config-conflict"],"backgroundTag":"unsupported-feature-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}