{"record":{"id":"f244bda0c5eb6cc2","repo":"sgl-project/sglang","slug":"hisparse-requires-one-of-hisparse-kv-cache-dtypes","errorCode":null,"errorMessage":"HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache dtypes, but got --kv-cache-dtype={kv_cache_dtype}. Please use {choices}.","messagePattern":"HiSparse requires one of (.+?) KV cache dtypes, but got --kv-cache-dtype=(.+?)\\. Please use (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/hisparse_hook.py","lineNumber":76,"sourceCode":"            f\"HiSparse supports DSA {label} backend(s) {sorted(allowed_backends)} \"\n            f\"on this platform with --kv-cache-dtype={kv_cache_dtype}, \"\n            f\"but got --dsa-{label}-backend={backend}. \"\n            f\"Please use one of {sorted(allowed_backends)}, or omit the option \"\n            \"to let SGLang pick a backend for this platform.\"\n        )\n\n\ndef validate_hisparse_kv_cache_dtype(server_args: ServerArgs) -> None:\n    from sglang.srt.arg_groups.overrides import resolved_view\n\n    kv_cache_dtype = resolved_view(server_args).kv_cache_dtype\n    if kv_cache_dtype in HISPARSE_KV_CACHE_DTYPES:\n        return\n\n    choices = \" or \".join(\n        f\"--kv-cache-dtype={dtype}\" for dtype in HISPARSE_KV_CACHE_DTYPES\n    )\n    raise ValueError(\n        f\"HiSparse requires one of {HISPARSE_KV_CACHE_DTYPES} KV cache dtypes, \"\n        f\"but got --kv-cache-dtype={kv_cache_dtype}. Please use {choices}.\"\n    )\n\n\ndef validate_hisparse(server_args: ServerArgs) -> None:\n    \"\"\"Validate --enable-hisparse constraints (model class, radix cache, DSA backend).\"\"\"\n    cfg = resolving_view(server_args)\n    if not cfg.enable_hisparse:\n        return\n\n    from sglang.srt.configs.model_config import (\n        is_deepseek_dsa,\n        is_deepseek_v4,\n    )\n\n    hf_config = server_args.get_model_config().hf_config\n    is_v4_hisparse = is_deepseek_v4(hf_config)","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/hisparse_hook.py#L58-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --kv-cache-dtype to one of the values printed in the message (e.g. fp8_e4m3)","Remove an explicit --kv-cache-dtype only if the default matches an allowed value — otherwise set it explicitly","If you can't change dtype, disable --enable-hisparse"],"exampleFix":"# before\n--enable-hisparse --kv-cache-dtype bf16\n# after\n--enable-hisparse --kv-cache-dtype fp8_e4m3","handlingStrategy":"validation","validationCode":"from sglang.srt.arg_groups.hisparse_hook import HISPARSE_KV_CACHE_DTYPES\nif enable_hisparse and kv_cache_dtype not in HISPARSE_KV_CACHE_DTYPES:\n    kv_cache_dtype = HISPARSE_KV_CACHE_DTYPES[0]","typeGuard":null,"tryCatchPattern":"except ValueError as e:\n    if 'HiSparse requires' in str(e): server_args.kv_cache_dtype = 'fp8_e4m3'; retry()\n    raise","preventionTips":["Pair --enable-hisparse with the documented kv-cache-dtype in shared launch snippets","Warn in config linting when hisparse and an off-list dtype coexist"],"tags":["hisparse","kv-cache-dtype","sglang","config-validation"],"backgroundTag":"incompatible-dtype-configuration","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}