sgl-project/sglang · error · ValueError

HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache

Error message

HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache dtypes, but got --kv-cache-dtype={kv_cache_dtype}. Please use {choices}.

What it means

HiSparse (DeepSeek sparse attention) kernels only work with specific KV cache dtypes (the tuple HISPARSE_KV_CACHE_DTYPES). If you enable HiSparse with any other --kv-cache-dtype, validation fails before launch with the list of valid choices.

Source

Thrown at python/sglang/srt/arg_groups/hisparse_hook.py:76

            f"HiSparse supports DSA {label} backend(s) {sorted(allowed_backends)} "
            f"on this platform with --kv-cache-dtype={kv_cache_dtype}, "
            f"but got --dsa-{label}-backend={backend}. "
            f"Please use one of {sorted(allowed_backends)}, or omit the option "
            "to let SGLang pick a backend for this platform."
        )


def validate_hisparse_kv_cache_dtype(server_args: ServerArgs) -> None:
    from sglang.srt.arg_groups.overrides import resolved_view

    kv_cache_dtype = resolved_view(server_args).kv_cache_dtype
    if kv_cache_dtype in HISPARSE_KV_CACHE_DTYPES:
        return

    choices = " or ".join(
        f"--kv-cache-dtype={dtype}" for dtype in HISPARSE_KV_CACHE_DTYPES
    )
    raise ValueError(
        f"HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache dtypes, "
        f"but got --kv-cache-dtype={kv_cache_dtype}. Please use {choices}."
    )


def validate_hisparse(server_args: ServerArgs) -> None:
    """Validate --enable-hisparse constraints (model class, radix cache, DSA backend)."""
    cfg = resolving_view(server_args)
    if not cfg.enable_hisparse:
        return

    from sglang.srt.configs.model_config import (
        is_deepseek_dsa,
        is_deepseek_v4,
    )

    hf_config = server_args.get_model_config().hf_config
    is_v4_hisparse = is_deepseek_v4(hf_config)

View on GitHub (pinned to 0132848349)

Solutions

1. Set --kv-cache-dtype to one of the values printed in the message (e.g. fp8_e4m3)
2. Remove an explicit --kv-cache-dtype only if the default matches an allowed value — otherwise set it explicitly
3. If you can't change dtype, disable --enable-hisparse

Example fix

# before
--enable-hisparse --kv-cache-dtype bf16
# after
--enable-hisparse --kv-cache-dtype fp8_e4m3

from sglang.srt.arg_groups.hisparse_hook import HISPARSE_KV_CACHE_DTYPES
if enable_hisparse and kv_cache_dtype not in HISPARSE_KV_CACHE_DTYPES:
    kv_cache_dtype = HISPARSE_KV_CACHE_DTYPES[0]

except ValueError as e:
    if 'HiSparse requires' in str(e): server_args.kv_cache_dtype = 'fp8_e4m3'; retry()
    raise

When it happens

Trigger: Running with --enable-hisparse while --kv-cache-dtype is not in HISPARSE_KV_CACHE_DTYPES (commonly fp8_e4m3 or fp8_e5m2 kernels requiring a specific dtype), during validate_hisparse.

Common situations: Reusing a launch recipe from a non-HiSparse config that set --kv-cache-dtype bf16 or auto; defaults differing from the HiSparse requirement after enabling the feature.

Related errors

• HiSparse supports DSA {label} backend(s) {sorted(allowed_bac
• TensorRT-LLM MLA backend only supports kv-cache-dtype of fp8
• tokenspeed_mla backend requires kv-cache-dtype=fp8_e4m3, got
• CuteDSL MLA backend only supports kv-cache-dtype of fp8_e4m3
• DeepSeekV4 only supports interleave CP strategy, got {cfg.cp

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