sgl-project/sglang · error · ValueError

'{upper}' is a reserved speculative algorithm name; cannot b

Error message

'{upper}' is a reserved speculative algorithm name; cannot be re-registered.

What it means

register_algorithm rejects names that collide with the built-in reserved SpeculativeAlgorithm names, so plugins cannot shadow built-in algorithms like EAGLE or NGRAM.

Source

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

            "so plugin-registered algorithms stay dispatchable."
        )


def register_algorithm(
    name: str,
    *,
    supports_overlap: bool = False,
    validate_server_args: Optional[ServerArgsValidator] = None,
    spec_class: Type[CustomSpecAlgo] = CustomSpecAlgo,
) -> Callable[[WorkerFactory], WorkerFactory]:
    """Return a decorator that registers a plugin algorithm under ``name``.

    Pass a ``spec_class`` subclass of ``CustomSpecAlgo`` to override any
    ``is_*()`` / ``supports_*()`` / ``create_worker`` method.
    """
    upper = name.upper()
    if upper in _reserved_names():
        raise ValueError(
            f"'{upper}' is a reserved speculative algorithm name; cannot be re-registered."
        )
    if upper in _REGISTRY:
        raise ValueError(f"Speculative algorithm '{upper}' already registered.")
    _assert_custom_spec_algo_conforms(spec_class)

    def decorator(factory: WorkerFactory) -> WorkerFactory:
        _REGISTRY[upper] = spec_class(
            name=upper,
            factory=factory,
            supports_overlap=supports_overlap,
            validate_server_args=validate_server_args,
        )
        return factory

    return decorator

View on GitHub (pinned to 0132848349)

Solutions

1. Rename your plugin algorithm to something unique (e.g. 'MY_EAGLE_VARIANT')
2. If you want built-in behavior, don't register — just use the built-in name in --speculative-algorithm

Example fix

# before
@register_algorithm('EAGLE')
# after
@register_algorithm('MY_EAGLE_VARIANT')

from sglang.srt.speculative.spec_registry import _reserved_names
assert name.upper() not in _reserved_names(), f'{name} is reserved'

def is_reserved_name(name: str) -> bool:
    return name.upper() in _reserved_names()

When it happens

Trigger: Calling @register_algorithm('EAGLE') or any name whose uppercase form appears in _reserved_names().

Common situations: A plugin intentionally or accidentally naming itself after a built-in algorithm; name collisions after new built-ins are added in upgrades.

Related errors

• {spec_class.__name__} is missing duck-typed methods from Spe
• Speculative algorithm '{upper}' already registered.
• This browser cannot encode H.264 MP4
• kv-canary: launch_canary_plan_kernels_torch_reference verify
• HiSparse speculative swap requires 2-4 steps, got {num_steps

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