{"record":{"id":"d5a97f5076b7adab","repo":"sgl-project/sglang","slug":"prefill-only-disable-kv-cache-is-incompatible-wi-d5a97f","errorCode":null,"errorMessage":"--prefill-only-disable-kv-cache is incompatible with --enable-hisparse: HiSparse uses a dedicated pool family that is not the no-op MHA pool.","messagePattern":"--prefill-only-disable-kv-cache is incompatible with --enable-hisparse: HiSparse uses a dedicated pool family that is not the no-op MHA pool\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":8211,"sourceCode":"        # which writes to the pool via set_kv_buffer. NoOpMHATokenToKVPool intentionally\n        # raises on writes, so the engine would boot fine but fail on the first request.\n        if self._resolved().attn_cp_size > 1:\n            raise ValueError(\n                \"--prefill-only-disable-kv-cache is incompatible with --attn-cp-size > 1: \"\n                \"the context-parallel attention path writes K/V to the pool via set_kv_buffer, \"\n                \"which the no-op pool intentionally rejects.\"\n            )\n        if cfg.enable_prefill_cp:\n            raise ValueError(\n                \"--prefill-only-disable-kv-cache is incompatible with \"\n                \"--enable-prefill-cp: the prefill-CP path stages K/V through \"\n                \"the paged cache, which the no-op pool does not support.\"\n            )\n\n        # HiSparse selects a different pool class (HiSparseDSATokenToKVPool /\n        # HiSparseTokenToKVPoolAllocator) that is not the no-op pool.\n        if cfg.enable_hisparse:\n            raise ValueError(\n                \"--prefill-only-disable-kv-cache is incompatible with --enable-hisparse: \"\n                \"HiSparse uses a dedicated pool family that is not the no-op MHA pool.\"\n            )\n\n    def _handle_prefill_only_disable_kv_cache(self):\n        \"\"\"Validate --prefill-only-disable-kv-cache backend constraint.\n\n        Must run after _handle_attention_backend_compatibility() (which fills\n        the default attention_backend if unset) and _handle_multi_item_scoring()\n        (which may further mutate it). The assertion below guards against\n        accidental call-site reordering: if the resolved attention_backend is\n        still None, backends haven't settled yet and the resolved (prefill,\n        decode) pair would be a stale (None, None).\n        \"\"\"\n        cfg = resolving_view(self)\n\n        if not cfg.prefill_only_disable_kv_cache:\n            return","sourceCodeStart":8193,"sourceCodeEnd":8229,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L8193-L8229","documentation":"HiSparse attention selects its own KV pool family (HiSparseDSATokenToKVPool / HiSparseTokenToKVPoolAllocator) instead of the no-op MHA pool that --prefill-only-disable-kv-cache installs, so the two cannot be combined; the validator rejects --enable-hisparse with the flag.","triggerScenarios":"Launching with --prefill-only-disable-kv-cache and --enable-hisparse (cfg.enable_hisparse true).","commonSituations":"A user experimenting with sparse-attention memory savings also turns on KV-cache disabling for an embedding workload, doubling up incompatible memory optimizations.","solutions":["Remove --enable-hisparse when using --prefill-only-disable-kv-cache","Choose one memory optimization: either HiSparse with a real pool, or the no-op pool without HiSparse","Check for a launcher script/profile that silently adds --enable-hisparse"],"exampleFix":"# before\n--prefill-only-disable-kv-cache --enable-hisparse\n# after\n--prefill-only-disable-kv-cache","handlingStrategy":"validation","validationCode":"if want_disable_kv_cache and enable_hisparse:\n    raise SystemExit(\"choose either --enable-hisparse or --prefill-only-disable-kv-cache\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick exactly one KV memory strategy per deployment","Check that profiles/launchers don't auto-inject sparse-attention flags"],"tags":["sglang","hisparse","sparse-attention","kv-cache","server-args"],"backgroundTag":"unsupported-config-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}