sgl-project/sglang · error · ValueError

Unknown sparse algorithm: {algorithm_name}

Error message

Unknown sparse algorithm: {algorithm_name}

What it means

The sparse algorithm factory looks up config.algorithm.lower() in _ALGORITHM_REGISTRY; an unknown name raises ValueError('Unknown sparse algorithm: ...'). Only algorithms registered in the factory (e.g. quest, and the DeepSeek DSA entries) can be created.

Source

Thrown at python/sglang/srt/mem_cache/sparsity/factory.py:40

_ALGORITHM_REGISTRY = {
    "quest": lambda config, device, **kw: QuestAlgorithm(config, device, **kw),
    "deepseek_dsa": lambda config, device, **kw: DeepSeekDSAAlgorithm(
        config, device, **kw
    ),
}


def _create_sparse_algorithm(
    config: SparseConfig,
    device: torch.device,
    **kwargs,
) -> BaseSparseAlgorithm:
    algorithm_name = config.algorithm.lower()
    factory = _ALGORITHM_REGISTRY.get(algorithm_name)

    if factory is None:
        raise ValueError(f"Unknown sparse algorithm: {algorithm_name}")

    return factory(config, device, **kwargs)


def _create_backend_adaptor(
    backend: str,
    device: torch.device,
    sparse_algorithm: BaseSparseAlgorithm,
    req_to_token_pool,
):
    """Create backend adaptor."""
    if isinstance(sparse_algorithm, DeepSeekDSAAlgorithm):
        return DSABackendAdaptor(device, req_to_token_pool)

    if backend in ["fa3", "flashattention"]:
        return FlashAttentionAdaptor(device)

    raise ValueError(f"Unknown attention backend: {backend}")

View on GitHub (pinned to 0132848349)

Solutions

1. Check the registry keys in sglang.srt.mem_cache.sparsity.factory._ALGORITHM_REGISTRY and use an exact (case-insensitive) name
2. Upgrade/downgrade sglang to the version that implements the algorithm you want
3. Fix typos in the algorithm config string

Example fix

# before
config.algorithm = "qest"
# after
config.algorithm = "quest"

from sglang.srt.mem_cache.sparsity.factory import _ALGORITHM_REGISTRY
name = config.algorithm.lower()
if name not in _ALGORITHM_REGISTRY:
    raise ValueError(f"unknown sparse algorithm {name}; valid: {sorted(_ALGORITHM_REGISTRY)}")

When it happens

Trigger: Calling create_sparse_coordinator / _create_sparse_algorithm with config.algorithm set to an unregistered string — typo (e.g. 'Qest', 'topk-quest'), or a name from a newer/older version.

Common situations: Setting the sparse attention algorithm via config/CLI with a misspelled or version-mismatched name; a docs example referencing an algorithm not present in the installed sglang version.

Related errors

• forward_batch with seq_lens is required for TopK retrieval
• Required: indexer, forward_batch, x, q_lora, positions
• Quest query hidden size {hidden} not divisible by head_dim {
• Unsupported query shape for Quest: {queries.shape}
• Query heads {q_heads} not divisible by KV heads {kv_heads}

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