sgl-project/sglang · error · ValueError

Unknown speculative algorithm name: {name}

Error message

Unknown speculative algorithm name: {name}

What it means

SpeculativeAlgorithm.from_string maps a --speculative-algorithm CLI string to an enum/registered algorithm. If the name matches neither a built-in enum member (uppercased) nor a plugin-registered algorithm, it raises ValueError.

Source

Thrown at python/sglang/srt/speculative/spec_info.py:61

    STANDALONE = auto()
    NGRAM = auto()
    NONE = auto()

    @classmethod
    def from_string(
        cls, name: Optional[str]
    ) -> Union[SpeculativeAlgorithm, CustomSpecAlgo]:
        if name is None:
            return cls.NONE
        upper = name.upper()
        try:
            return cls[upper]
        except KeyError:
            pass
        spec = _get_registered_spec(upper)
        if spec is not None:
            return spec
        raise ValueError(f"Unknown speculative algorithm name: {name}")

    @classmethod
    def register(
        cls,
        name: str,
        *,
        supports_overlap: bool = False,
        validate_server_args: Optional[ServerArgsValidator] = None,
        spec_class: Type[CustomSpecAlgo] = CustomSpecAlgo,
    ) -> Callable[[WorkerFactory], WorkerFactory]:
        """Decorator to register a plugin speculative algorithm. The factory
        takes ``server_args`` and returns the worker class. Pass a
        ``CustomSpecAlgo`` subclass via ``spec_class`` to override any
        ``is_*()`` / ``create_worker`` method.

        Example:
            @SpeculativeAlgorithm.register("MY_SPEC", supports_overlap=False)
            def _factory(server_args):

View on GitHub (pinned to 0132848349)

Solutions

1. Check spelling against the SpeculativeAlgorithm enum members and registered plugin names
2. If a plugin algorithm, ensure its module is imported (entry point 'sglang.platform_plugins' or explicit import) before from_string runs
3. List valid names: [m.name for m in SpeculativeAlgorithm] plus registry keys

Example fix

// before
--speculative-algorithm EAGLE3X  # typo
// after
--speculative-algorithm EAGLE3

from sglang.srt.speculative.spec_info import SpeculativeAlgorithm
name = 'EAGLE3'
valid = {m.name for m in SpeculativeAlgorithm}
assert name in valid, f'{name} not in {sorted(valid)}'

def is_known_algorithm(name: str) -> bool:
    upper = name.upper()
    try:
        SpeculativeAlgorithm[upper]
        return True
    except KeyError:
        return _get_registered_spec(upper) is not None

try:
    algo = SpeculativeAlgorithm.from_string(name)
except ValueError as e:
    raise SystemExit(f'Bad --speculative-algorithm: {e}') from e

When it happens

Trigger: Passing a typo'd or unsupported algorithm name to --speculative-algorithm, e.g. 'ealg' instead of 'EAGLE', or a plugin name whose registering module was never imported.

Common situations: Typos in server args, outdated algorithm names after renames, or missing plugin entry point / missing import of the module calling register_algorithm.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Speculative algorithm {self.name} does not support overlap s
• Unknown speculative phase: {phase}
• Invalid simulate_acc_method: {simulate_acc_method}
• This browser cannot encode H.264 MP4
• Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_

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