vllm-project/vllm · error · ValueError

Hybrid KV cache manager was explicitly enabled but is not su

Error message

Hybrid KV cache manager was explicitly enabled but is not supported in this configuration. Consider omitting the --no-disable-hybrid-kv-cache-manager flag to let vLLM decide automatically.

What it means

vLLM auto-disables the hybrid KV cache manager when the configuration does not support HMA (as computed by `need_disable_hybrid_kv_cache_manager`). If the user explicitly forced the manager on with `--no-disable-hybrid-kv-cache-manager` but the config still needs it off, validation raises instead of silently overriding the user.

Source

Thrown at vllm/config/vllm.py:1779

                        "Turning off hybrid kv cache manager because "
                        "`--kv-transfer-config` selects a KV connector that "
                        "does not support it. Impact: hybrid SSM models "
                        "(e.g. Jamba, Bamba) require HMA and will fail at "
                        "startup without it; models with sliding window "
                        "attention will run with reduced performance. "
                        "To add HMA support to a KV connector, subclass "
                        "`SupportsHMA` defined in kv_connector/v1/base.py "
                        "(for MultiConnector, all child connectors must "
                        "support HMA)."
                    )
            self.scheduler_config.disable_hybrid_kv_cache_manager = (
                need_disable_hybrid_kv_cache_manager
            )
        elif (
            self.scheduler_config.disable_hybrid_kv_cache_manager is False
            and need_disable_hybrid_kv_cache_manager
        ):
            raise ValueError(
                "Hybrid KV cache manager was explicitly enabled but is not "
                "supported in this configuration. Consider omitting the "
                "--no-disable-hybrid-kv-cache-manager flag to let vLLM decide"
                " automatically."
            )

        if self.scheduler_config.disable_hybrid_kv_cache_manager is None:
            # Default to enable HMA if not explicitly disabled by user or logic above.
            self.scheduler_config.disable_hybrid_kv_cache_manager = False

        if self.compilation_config.debug_dump_path:
            self.compilation_config.debug_dump_path = (
                self.compilation_config.debug_dump_path.absolute().expanduser()
            )
        if envs.VLLM_DEBUG_DUMP_PATH is not None:
            env_path = Path(envs.VLLM_DEBUG_DUMP_PATH).absolute().expanduser()
            if self.compilation_config.debug_dump_path:
                logger.warning(

View on GitHub (pinned to c794754062)

Solutions

1. Remove `--no-disable-hybrid-kv-cache-manager` and let vLLM decide automatically.
2. Identify the incompatible feature/connector from the auto-disable logic and drop it if HMA matters more.
3. If a custom KV connector is involved, implement `SupportsHMA` (kv_connector/v1/base.py; for MultiConnector every child must support it).

Example fix

# before
vllm serve model --no-disable-hybrid-kv-cache-manager \
  --kv-transfer-config '{...connector...}'

# after
vllm serve model --kv-transfer-config '{...connector...}'

# simplest guard: never force it on
if kv_connector_used and disable_hybrid_kv_cache_manager is False:
    disable_hybrid_kv_cache_manager = None  # let vLLM auto-decide

try:
    LLM(**args)
except ValueError as e:
    if "Hybrid KV cache manager was explicitly enabled" in str(e):
        args["scheduler_config"].disable_hybrid_kv_cache_manager = None
    else:
        raise

When it happens

Trigger: Passing `--no-disable-hybrid-kv-cache-manager` (setting scheduler_config.disable_hybrid_kv_cache_manager=False) while a detected condition requires the hybrid manager to be disabled (e.g. a KV connector or feature lacking HMA support).

Common situations: Enabling the hybrid KV cache manager for hybrid attention models while simultaneously using a KV transfer connector or feature that does not subclass `SupportsHMA`; overriding the auto-disable without realizing which feature forced it.

Related errors

• MoRIIO KV cache block size mismatch for layer {layer_name}:
• Unknown KV cache group kind '{kind}' in backend_per_kind. Va
• offload_num_in_group ({self.prefetch.offload_num_in_group})
• Stochastic rounding for Mamba cache requires the SSM cache t
• Currently, async scheduling is only supported with EAGLE/MTP

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/e0a84faa0c8e0991. Report an issue: GitHub.