sgl-project/sglang · error · ValueError

LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}.

Error message

LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}.

What it means

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).

Source

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

                "swap does not rebuild LoRA cuda-graph metadata",
            ),
            (
                "experimental_sgl_trtllm"
                in (cfg.moe_runner_backend, cfg.speculative_moe_runner_backend),
                "does not support the experimental_sgl_trtllm MoE runner: its "
                "TopK reads the LoRA config per forward, which the draft "
                "resolves against the target's after its own publish ended",
            ),
            (
                envs.SGLANG_ENABLE_OVERLAP_PLAN_STREAM.get(),
                "does not support SGLANG_ENABLE_OVERLAP_PLAN_STREAM=1: LoRA "
                "batch preparation would run on the plan stream, unordered "
                "against in-flight forwards",
            ),
        ]
        for is_unsupported, reason in unsupported:
            if is_unsupported:
                raise ValueError(
                    f"LoRA with EAGLE/NEXTN/EAGLE3 speculative decoding {reason}."
                )

    def validate_buckets_rule(self, arg_name: str, buckets_rule: List[str]):
        if not buckets_rule:
            return

        assert len(buckets_rule) > 0, f"{arg_name} cannot be empty list"
        rule = buckets_rule[0]
        assert rule in [
            "tse",
            "default",
            "custom",
        ], f"Unsupported {arg_name} rule type: '{rule}'. Must be one of: 'tse', 'default', 'custom'"

        if rule == "tse":
            assert (
                len(buckets_rule) == 4

View on GitHub (pinned to 0132848349)

Solutions

1. Follow {reason}: disable the flagged feature (e.g. turn off the overlap/plan-stream mode it names)
2. Or disable LoRA for this run
3. Or switch to a spec algorithm without the restriction (NGRAM/DFLASH/DSPARK)

Example fix

# before
--speculative-algorithm EAGLE --enable-overlap-schedule --lora-paths '[...]'
# after
--speculative-algorithm EAGLE --lora-paths '[...]'  # overlap off

if lora_paths and speculative_algorithm in {'EAGLE','NEXTN','EAGLE3'} and overlap_enabled:
    raise SystemExit('EAGLE+LoRA does not support this scheduling mode')

When it happens

Trigger: Enabling --lora-paths with EAGLE/NEXTN/EAGLE3 spec decoding while the flagged condition is active (specific overlap/plan-stream scheduling modes).

Common situations: Turning on overlap scheduling or plan-stream features that EAGLE LoRA support does not yet cover; version upgrades adding new unsupported combos.

Related errors

• LoRA is only compatible with NGRAM, EAGLE, NEXTN, EAGLE3, DF
• --enable-linear-replayssm-spec requires a linear draft chain
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• --disaggregation-decode-enable-radix-cache is incompatible w
• Gemma4AssistantForCausalLM draft requires --speculative-algo

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