{"record":{"id":"aaead811d0809fef","repo":"sgl-project/sglang","slug":"lora-with-eagle-nextn-eagle3-speculative-decoding","errorCode":null,"errorMessage":"LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}.","messagePattern":"LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":10731,"sourceCode":"                \"swap does not rebuild LoRA cuda-graph metadata\",\n            ),\n            (\n                \"experimental_sgl_trtllm\"\n                in (cfg.moe_runner_backend, cfg.speculative_moe_runner_backend),\n                \"does not support the experimental_sgl_trtllm MoE runner: its \"\n                \"TopK reads the LoRA config per forward, which the draft \"\n                \"resolves against the target's after its own publish ended\",\n            ),\n            (\n                envs.SGLANG_ENABLE_OVERLAP_PLAN_STREAM.get(),\n                \"does not support SGLANG_ENABLE_OVERLAP_PLAN_STREAM=1: LoRA \"\n                \"batch preparation would run on the plan stream, unordered \"\n                \"against in-flight forwards\",\n            ),\n        ]\n        for is_unsupported, reason in unsupported:\n            if is_unsupported:\n                raise ValueError(\n                    f\"LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}.\"\n                )\n\n    def validate_buckets_rule(self, arg_name: str, buckets_rule: List[str]):\n        if not buckets_rule:\n            return\n\n        assert len(buckets_rule) > 0, f\"{arg_name} cannot be empty list\"\n        rule = buckets_rule[0]\n        assert rule in [\n            \"tse\",\n            \"default\",\n            \"custom\",\n        ], f\"Unsupported {arg_name} rule type: '{rule}'. Must be one of: 'tse', 'default', 'custom'\"\n\n        if rule == \"tse\":\n            assert (\n                len(buckets_rule) == 4","sourceCodeStart":10713,"sourceCodeEnd":10749,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L10713-L10749","documentation":"Raised when LoRA is combined with EAGLE/NEXTN/EAGLE3 speculative decoding in an unsupported configuration; {reason} describes the specific unsupported condition (e.g. batch preparation running on the plan stream unordered against in-flight forwards).","triggerScenarios":"Enabling --lora-paths with EAGLE/NEXTN/EAGLE3 spec decoding while the flagged condition is active (specific overlap/plan-stream scheduling modes).","commonSituations":"Turning on overlap scheduling or plan-stream features that EAGLE LoRA support does not yet cover; version upgrades adding new unsupported combos.","solutions":["Follow {reason}: disable the flagged feature (e.g. turn off the overlap/plan-stream mode it names)","Or disable LoRA for this run","Or switch to a spec algorithm without the restriction (NGRAM/DFLASH/DSPARK)"],"exampleFix":"# before\n--speculative-algorithm EAGLE --enable-overlap-schedule --lora-paths '[...]'\n# after\n--speculative-algorithm EAGLE --lora-paths '[...]'  # overlap off","handlingStrategy":"validation","validationCode":"if lora_paths and speculative_algorithm in {'EAGLE','NEXTN','EAGLE3'} and overlap_enabled:\n    raise SystemExit('EAGLE+LoRA does not support this scheduling mode')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Read the {reason} suffix — it names the exact unsupported condition","Keep EAGLE+LoRA configs minimal; avoid new scheduling flags until tested"],"tags":["sglang","lora","eagle","speculative-decoding","feature-incompatibility"],"backgroundTag":"incompatible-feature-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}