sgl-project/sglang · error · ValueError

LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, DF

Error message

LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, or DSPARK speculative decoding, not {cfg.speculative_algorithm}{promoted}.

What it means

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.

Source

Thrown at python/sglang/srt/server_args.py:10692

        Adapters apply to the target only; a shared draft runs unadapted.
        Matches resolved algorithm names (NEXTN has collapsed to EAGLE).
        """
        cfg = resolving_view(self)
        if cfg.speculative_algorithm in ["NGRAM", None]:
            return

        # These algorithms present a uniform per-request token width during
        # verify, which is what the LoRA segment layout assumes.
        lora_spec_algorithms = ("EAGLE", "EAGLE3", "DFLASH", "DSPARK")
        if cfg.speculative_algorithm not in lora_spec_algorithms:
            promoted = (
                " (NEXTN/EAGLE with a Gemma4 assistant draft is automatically "
                "promoted to FROZEN_KV_MTP, which does not support LoRA)"
                if cfg.speculative_algorithm == "FROZEN_KV_MTP"
                else ""
            )
            raise ValueError(
                "LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, "
                "DFLASH, or DSPARK speculative decoding, not "
                f"{cfg.speculative_algorithm}{promoted}."
            )

        ragged_mode = envs.SGLANG_RAGGED_VERIFY_MODE.get()

        # Each entry: (is unsupported, why). Reasons are appended to a shared
        # prefix so the message names the combination, not just the flag.
        unsupported = [
            (
                cfg.speculative_algorithm == "DSPARK" and ragged_mode != "static",
                f"does not support SGLANG_RAGGED_VERIFY_MODE={ragged_mode!r}: "
                "the per-request verify lengths it schedules break the "
                "uniform-width LoRA segment layout",
            ),
            (
                cfg.speculative_adaptive,

View on GitHub (pinned to 0132848349)

Solutions

1. Disable LoRA (--lora-paths) when using an incompatible speculative algorithm
2. Or switch --speculative-algorithm to one of NGRAM, EAGLE, NEXTN, EAGLE3, DFLASH, DSPARK
3. For Gemma4 FROZEN_KV_MTP promotion, pick a different draft model or disable the frozen-KV path to keep LoRA

Example fix

# before
--speculative-algorithm FROZEN_KV_MTP --lora-paths '["/models/lora-a"]'
# after
--speculative-algorithm EAGLE --lora-paths '["/models/lora-a"]'

LORA_COMPAT_SPEC = {'NGRAM','EAGLE','NEXTN','EAGLE3','DFLASH','DSPARK'}
if lora_paths and speculative_algorithm not in LORA_COMPAT_SPEC:
    raise SystemExit(f'LoRA incompatible with {speculative_algorithm}')

catch ValueError at arg parsing and fall back to disabling either LoRA or spec decoding

When it happens

Trigger: Setting --lora-paths together with --speculative-algorithm set to an unsupported value (e.g. FROZEN_KV_MTP, STANDALONE, or another non-listed algorithm).

Common situations: 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.

Related errors

• LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}.
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• --disaggregation-decode-enable-radix-cache is incompatible w
• Gemma4AssistantForCausalLM draft requires --speculative-algo
• --speculative-draft-window-size must be positive, got {}.

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/e24b3b474b5dedf9. Report an issue: GitHub.