{"record":{"id":"8840061d8cca8e01","repo":"sgl-project/sglang","slug":"speculative-eagle-topk-1-with-page-size-1-is-o","errorCode":null,"errorMessage":"speculative_eagle_topk > 1 with page_size > 1 is only supported on {_PAGE_TREE_SPEC_BACKENDS}; got attention_backend={view.attention_backend!r}. Use page_size == 1 or one of those backends.","messagePattern":"speculative_eagle_topk > 1 with page_size > 1 is only supported on (.+?); got attention_backend=(.+?)\\. Use page_size == 1 or one of those backends\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/speculative_hook.py","lineNumber":838,"sourceCode":"            \"speculative_num_draft_tokens is adjusted to speculative_num_steps + 1 when speculative_eagle_topk == 1\"\n        )\n        declare_resolution(\n            server_args,\n            \"_handle_eagle_family\",\n            speculative_num_draft_tokens=cfg.speculative_num_steps + 1,\n        )\n\n    # topk > 1 + page_size > 1 needs the two-pass cascade draft-decode (shared prefix\n    # pass + per-branch expand pass with prefix-tail dup). Only these backends implement\n    # it; flashmla / trtllm_mla / cutlass_mla can't express the per-branch tree, so reject.\n    _PAGE_TREE_SPEC_BACKENDS = (\"flashinfer\", \"fa3\", \"triton\")\n    view = resolved_view(server_args)\n    if (\n        cfg.speculative_eagle_topk > 1\n        and view.page_size > 1\n        and view.attention_backend not in _PAGE_TREE_SPEC_BACKENDS\n    ):\n        raise ValueError(\n            f\"speculative_eagle_topk > 1 with page_size > 1 is only supported on \"\n            f\"{_PAGE_TREE_SPEC_BACKENDS}; got attention_backend=\"\n            f\"{view.attention_backend!r}. Use page_size == 1 or one of those backends.\"\n        )\n\n\ndef _handle_ngram(server_args: ServerArgs) -> None:\n    cfg = resolving_view(server_args)\n    if cfg.device not in (\"cuda\", \"cpu\"):\n        raise ValueError(\n            \"Ngram speculative decoding only supports CUDA or CPU devices.\"\n        )\n\n    _disable_overlap_schedule_for_cpu(server_args)\n\n    if cfg.max_running_requests is None:\n        declare_resolution(\n            server_args,","sourceCodeStart":820,"sourceCodeEnd":856,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/speculative_hook.py#L820-L856","documentation":"Tree-based EAGLE drafting (speculative_eagle_topk > 1) requires the attention backend to support paged KV for a draft tree when page_size > 1. Only backends in _PAGE_TREE_SPEC_BACKENDS implement tree-shaped page tables; others (e.g. FlashInfer variants without tree paging) cannot store the branching draft tokens under multi-token pages, so the combination is rejected.","triggerScenarios":"Launching with speculative EAGLE where speculative_eagle_topk > 1 and the resolved page_size > 1 while attention_backend resolves to a backend not in _PAGE_TREE_SPEC_BACKENDS (e.g. some FlashMLA/FlashInfer/Triton configs).","commonSituations":"Forcing an attention backend for perf tuning (e.g. --attention-backend triton) on a page-size>1 setup while keeping tree drafting; using DP/TP hardware presets that default to a non-tree backend with page_size>1; recent SGLang versions that added page_size>1 defaults.","solutions":["Set --page-size 1","Or switch to one of the tree-capable backends listed in _PAGE_TREE_SPEC_BACKENDS (check speculative_hook.py for the current list)","Or reduce --speculative-eagle-topk to 1 (linear chain works on any backend)"],"exampleFix":"# before\n--speculative-eagle-topk 8 --page-size 64 --attention-backend triton\n# after\n--speculative-eagle-topk 8 --page-size 1","handlingStrategy":"validation","validationCode":"from sglang.srt.arg_groups.speculative_hook import _PAGE_TREE_SPEC_BACKENDS\nfrom sglang.srt.arg_groups.overrides import resolved_view\nv = resolved_view(server_args)\nif server_args.speculative_eagle_topk > 1 and v.page_size > 1:\n    assert v.attention_backend in _PAGE_TREE_SPEC_BACKENDS, \"tree spec + page>1 needs tree-capable backend\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to --page-size 1 when using tree drafting unless the backend is known to support it","Check the backend list in speculative_hook.py when upgrading SGLang"],"tags":["speculative-decoding","eagle-topk","page-size","attention-backend","server-args"],"backgroundTag":"unsupported-attention-backend-config","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}