{"record":{"id":"e24b3b474b5dedf9","repo":"sgl-project/sglang","slug":"lora-is-only-compatible-with-ngram-eagle-nextn","errorCode":null,"errorMessage":"LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, or DSPARK speculative decoding, not {cfg.speculative_algorithm}{promoted}.","messagePattern":"LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, or DSPARK speculative decoding, not (.+?)(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":10692,"sourceCode":"\n        Adapters apply to the target only; a shared draft runs unadapted.\n        Matches resolved algorithm names (NEXTN has collapsed to EAGLE).\n        \"\"\"\n        cfg = resolving_view(self)\n        if cfg.speculative_algorithm in [\"NGRAM\", None]:\n            return\n\n        # These algorithms present a uniform per-request token width during\n        # verify, which is what the LoRA segment layout assumes.\n        lora_spec_algorithms = (\"EAGLE\", \"EAGLE3\", \"DFLASH\", \"DSPARK\")\n        if cfg.speculative_algorithm not in lora_spec_algorithms:\n            promoted = (\n                \" (NEXTN/EAGLE with a Gemma4 assistant draft is automatically \"\n                \"promoted to FROZEN_KV_MTP, which does not support LoRA)\"\n                if cfg.speculative_algorithm == \"FROZEN_KV_MTP\"\n                else \"\"\n            )\n            raise ValueError(\n                \"LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, \"\n                \"DFLASH, or DSPARK speculative decoding, not \"\n                f\"{cfg.speculative_algorithm}{promoted}.\"\n            )\n\n        ragged_mode = envs.SGLANG_RAGGED_VERIFY_MODE.get()\n\n        # Each entry: (is unsupported, why). Reasons are appended to a shared\n        # prefix so the message names the combination, not just the flag.\n        unsupported = [\n            (\n                cfg.speculative_algorithm == \"DSPARK\" and ragged_mode != \"static\",\n                f\"does not support SGLANG_RAGGED_VERIFY_MODE={ragged_mode!r}: \"\n                \"the per-request verify lengths it schedules break the \"\n                \"uniform-width LoRA segment layout\",\n            ),\n            (\n                cfg.speculative_adaptive,","sourceCodeStart":10674,"sourceCodeEnd":10710,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L10674-L10710","documentation":"Raised when LoRA is enabled together with a speculative decoding algorithm that does not support it. Only NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, and DSPARK are LoRA-compatible; FROZEN_KV_MTP (auto-promoted from NEXTN/EAGLE with a Gemma4 draft) is explicitly incompatible.","triggerScenarios":"Setting --lora-paths together with --speculative-algorithm set to an unsupported value (e.g. FROZEN_KV_MTP, STANDALONE, or another non-listed algorithm).","commonSituations":"Running a Gemma4 model whose NEXTN/EAGLE draft auto-promotes to FROZEN_KV_MTP while also attaching LoRA adapters; upgrading SGLang and hitting newly enforced compatibility rules.","solutions":["Disable LoRA (--lora-paths) when using an incompatible speculative algorithm","Or switch --speculative-algorithm to one of NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, DSPARK","For Gemma4 FROZEN_KV_MTP promotion, pick a different draft model or disable the frozen-KV path to keep LoRA"],"exampleFix":"# before\n--speculative-algorithm FROZEN_KV_MTP --lora-paths '[\"/models/lora-a\"]'\n# after\n--speculative-algorithm EAGLE --lora-paths '[\"/models/lora-a\"]'","handlingStrategy":"validation","validationCode":"LORA_COMPAT_SPEC = {'NGRAM','EAGLE','NEXTN','EAGLE3','DFLASH','DSPARK'}\nif lora_paths and speculative_algorithm not in LORA_COMPAT_SPEC:\n    raise SystemExit(f'LoRA incompatible with {speculative_algorithm}')","typeGuard":null,"tryCatchPattern":"catch ValueError at arg parsing and fall back to disabling either LoRA or spec decoding","preventionTips":["Check the compat matrix when combining LoRA with speculative decoding","Beware auto-promotion to FROZEN_KV_MTP for Gemma4 drafts"],"tags":["sglang","lora","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"}