{"record":{"id":"f9560420891054dc","repo":"sgl-project/sglang","slug":"prefill-only-disable-kv-cache-requires-disable","errorCode":null,"errorMessage":"--prefill-only-disable-kv-cache requires --disable-radix-cache because the radix cache indexes KV pool slots that no longer hold real data.","messagePattern":"--prefill-only-disable-kv-cache requires --disable-radix-cache because the radix cache indexes KV pool slots that no longer hold real data\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":8187,"sourceCode":"                \"--prefill-only-disable-kv-cache does not currently support \"\n                \"--kv-cache-dtype=mxfp8 because the MXFP8 pool stores separate \"\n                \"scale-factor buffers.\"\n            )\n\n        # Structural preconditions for the FA backend's fa_skip_kv_cache path,\n        # which is the only embedding path that doesn't read or write the pool:\n        # - chunked_prefill_size == -1 keeps a request in a single forward,\n        #   so K/V never has to be reused across prefill chunks.\n        # - disable_radix_cache stops the prefix cache from indexing pool\n        #   slots that no longer hold real data.\n        if cfg.chunked_prefill_size != -1:\n            raise ValueError(\n                \"--prefill-only-disable-kv-cache requires --chunked-prefill-size=-1 so the FA \"\n                \"backend takes the fa_skip_kv_cache path; otherwise the pool would be touched \"\n                \"between prefill chunks.\"\n            )\n        if not cfg.disable_radix_cache:\n            raise ValueError(\n                \"--prefill-only-disable-kv-cache requires --disable-radix-cache because the \"\n                \"radix cache indexes KV pool slots that no longer hold real data.\"\n            )\n\n        # Context-parallel prefill stages K/V through cp_allgather_and_save_kv_cache,\n        # 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.\"","sourceCodeStart":8169,"sourceCodeEnd":8205,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L8169-L8205","documentation":"When the KV pool is disabled, its slots hold no real data, so the radix (prefix) cache would index stale/garbage slots and serve wrong results. --prefill-only-disable-kv-cache therefore requires --disable-radix-cache.","triggerScenarios":"Launching with --prefill-only-disable-kv-cache without --disable-radix-cache (i.e. prefix caching is enabled by default or explicitly).","commonSituations":"A user enables the flag on an embedding server but leaves prefix caching on (the default), or a shared config template sets radix-cache-related flags.","solutions":["Add --disable-radix-cache to the launch command","Also disable derived prefix-cache features (e.g. HiCache settings) that imply radix caching","Rerun and confirm no other radix-cache-enabling flags remain"],"exampleFix":"# before\n--prefill-only-disable-kv-cache\n# after\n--prefill-only-disable-kv-cache --disable-radix-cache --chunked-prefill-size -1 --is-embedding","handlingStrategy":"validation","validationCode":"if want_disable_kv_cache and not disable_radix_cache:\n    raise SystemExit(\"add --disable-radix-cache with --prefill-only-disable-kv-cache\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Disable prefix caching and HiCache whenever the KV pool is disabled","Note that results would be silently wrong if this combination were allowed — treat the error as a correctness guard"],"tags":["sglang","radix-cache","prefix-cache","kv-cache","server-args"],"backgroundTag":"invalid-flag-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}