sgl-project/sglang · error · ValueError

Speculative algorithm {self.name} does not support overlap s

Error message

Speculative algorithm {self.name} does not support overlap scheduling.

What it means

When a speculative algorithm worker is created, the registry checks overlap-scheduling compatibility. If the server runs with overlap scheduling enabled (disable_overlap_schedule=False) and the algorithm's spec class declares supports_overlap=False, creation fails immediately.

Source

Thrown at python/sglang/srt/speculative/spec_registry.py:115

    def supports_grammar_overlap(self) -> bool:
        # Whether the worker advances the grammar FSM inside verify() (via the
        # scheduler's grammar barrier), letting spec + grammar decode overlap.
        return False

    def has_draft_kv(self) -> bool:
        # Conservative default: the larger KV reserve.
        return True

    def handle_server_args(self, server_args: ServerArgs) -> None:
        pass

    def create_worker(self, server_args: ServerArgs) -> Type:
        from sglang.srt.arg_groups.overrides import resolving_view

        cfg = resolving_view(server_args)
        if not cfg.disable_overlap_schedule and not self.supports_overlap:
            raise ValueError(
                f"Speculative algorithm {self.name} does not support overlap scheduling."
            )
        if not self.supports_overlap:
            # Reached only when overlap is disabled, so the algorithm really
            # does run synchronously on the V2 schema below.
            logger.warning(
                "Speculative algorithm %s is registered with "
                "supports_overlap=False, which is deprecated: the spec V1 "
                "worker path has been removed, and the algorithm now runs on "
                "the V2 scheduler schema with overlap disabled (synchronous). "
                "Migrate the plugin worker to support overlap scheduling.",
                self.name,
            )
        return self.factory(server_args)

    def get_num_tokens_per_req_for_target_verify(
        self, num_draft_tokens: int, is_draft_worker: bool
    ) -> int:

View on GitHub (pinned to 0132848349)

Solutions

1. Add --disable-overlap-schedule to the server launch
2. If you own the algorithm, implement overlap support and set supports_overlap() -> True
3. Switch to an algorithm that supports overlap (e.g. EAGLE-family)

Example fix

# before
python -m sglang.launch_server --model m --speculative-algorithm MYALGO
# after
python -m sglang.launch_server --model m --speculative-algorithm MYALGO --disable-overlap-schedule

algo = SpeculativeAlgorithm.from_string(name)
if not algo.supports_overlap and not server_args.disable_overlap_schedule:
    server_args.disable_overlap_schedule = True  # or abort with a clear message

def needs_overlap_disabled(name: str, server_args) -> bool:
    spec = SpeculativeAlgorithm.from_string(name)
    return not spec.supports_overlap and not server_args.disable_overlap_schedule

When it happens

Trigger: Launching with --speculative-algorithm <algo> while overlap scheduling is on (default) and the algorithm has supports_overlap() returning False, e.g. certain custom or NGram/STANDALONE variants that run synchronously.

Common situations: Default server flags combined with an algorithm that has not been made overlap-safe; plugin algorithms that forgot to override supports_overlap.

Related errors

• Unknown speculative algorithm name: {name}
• Invalid simulate_acc_method: {simulate_acc_method}
• This browser cannot encode H.264 MP4
• Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_
• Invalid arch format: {arch_str}

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