sgl-project/sglang · error · ValueError

--prefill-only-disable-kv-cache is incompatible with --enabl

Error message

--prefill-only-disable-kv-cache is incompatible with --enable-hisparse: HiSparse uses a dedicated pool family that is not the no-op MHA pool.

What it means

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.

Source

Thrown at python/sglang/srt/server_args.py:8211

        # which writes to the pool via set_kv_buffer. NoOpMHATokenToKVPool intentionally
        # raises on writes, so the engine would boot fine but fail on the first request.
        if self._resolved().attn_cp_size > 1:
            raise ValueError(
                "--prefill-only-disable-kv-cache is incompatible with --attn-cp-size > 1: "
                "the context-parallel attention path writes K/V to the pool via set_kv_buffer, "
                "which the no-op pool intentionally rejects."
            )
        if cfg.enable_prefill_cp:
            raise ValueError(
                "--prefill-only-disable-kv-cache is incompatible with "
                "--enable-prefill-cp: the prefill-CP path stages K/V through "
                "the paged cache, which the no-op pool does not support."
            )

        # HiSparse selects a different pool class (HiSparseDSATokenToKVPool /
        # HiSparseTokenToKVPoolAllocator) that is not the no-op pool.
        if cfg.enable_hisparse:
            raise ValueError(
                "--prefill-only-disable-kv-cache is incompatible with --enable-hisparse: "
                "HiSparse uses a dedicated pool family that is not the no-op MHA pool."
            )

    def _handle_prefill_only_disable_kv_cache(self):
        """Validate --prefill-only-disable-kv-cache backend constraint.

        Must run after _handle_attention_backend_compatibility() (which fills
        the default attention_backend if unset) and _handle_multi_item_scoring()
        (which may further mutate it). The assertion below guards against
        accidental call-site reordering: if the resolved attention_backend is
        still None, backends haven't settled yet and the resolved (prefill,
        decode) pair would be a stale (None, None).
        """
        cfg = resolving_view(self)

        if not cfg.prefill_only_disable_kv_cache:
            return

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --enable-hisparse when using --prefill-only-disable-kv-cache
2. Choose one memory optimization: either HiSparse with a real pool, or the no-op pool without HiSparse
3. Check for a launcher script/profile that silently adds --enable-hisparse

Example fix

# before
--prefill-only-disable-kv-cache --enable-hisparse
# after
--prefill-only-disable-kv-cache

if want_disable_kv_cache and enable_hisparse:
    raise SystemExit("choose either --enable-hisparse or --prefill-only-disable-kv-cache")

When it happens

Trigger: Launching with --prefill-only-disable-kv-cache and --enable-hisparse (cfg.enable_hisparse true).

Common situations: A user experimenting with sparse-attention memory savings also turns on KV-cache disabling for an embedding workload, doubling up incompatible memory optimizations.

Related errors

• MHATokenToKOnlyPool does not allocate V
• MHATokenToKOnlyPool: use set_index_k_buffer on the parent Mi
• layer_id={layer_id} does not have an index V cache (either d
• layer_id={layer_id} is not a sparse attention layer; sparse
• layer.layer_id={layer.layer_id} does not have an index V cac

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