{"record":{"id":"e0a84faa0c8e0991","repo":"vllm-project/vllm","slug":"hybrid-kv-cache-manager-was-explicitly-enabled-but","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1779,"sourceCode":"                        \"Turning off hybrid kv cache manager because \"\n                        \"`--kv-transfer-config` selects a KV connector that \"\n                        \"does not support it. Impact: hybrid SSM models \"\n                        \"(e.g. Jamba, Bamba) require HMA and will fail at \"\n                        \"startup without it; models with sliding window \"\n                        \"attention will run with reduced performance. \"\n                        \"To add HMA support to a KV connector, subclass \"\n                        \"`SupportsHMA` defined in kv_connector/v1/base.py \"\n                        \"(for MultiConnector, all child connectors must \"\n                        \"support HMA).\"\n                    )\n            self.scheduler_config.disable_hybrid_kv_cache_manager = (\n                need_disable_hybrid_kv_cache_manager\n            )\n        elif (\n            self.scheduler_config.disable_hybrid_kv_cache_manager is False\n            and need_disable_hybrid_kv_cache_manager\n        ):\n            raise ValueError(\n                \"Hybrid KV cache manager was explicitly enabled but is not \"\n                \"supported in this configuration. Consider omitting the \"\n                \"--no-disable-hybrid-kv-cache-manager flag to let vLLM decide\"\n                \" automatically.\"\n            )\n\n        if self.scheduler_config.disable_hybrid_kv_cache_manager is None:\n            # Default to enable HMA if not explicitly disabled by user or logic above.\n            self.scheduler_config.disable_hybrid_kv_cache_manager = False\n\n        if self.compilation_config.debug_dump_path:\n            self.compilation_config.debug_dump_path = (\n                self.compilation_config.debug_dump_path.absolute().expanduser()\n            )\n        if envs.VLLM_DEBUG_DUMP_PATH is not None:\n            env_path = Path(envs.VLLM_DEBUG_DUMP_PATH).absolute().expanduser()\n            if self.compilation_config.debug_dump_path:\n                logger.warning(","sourceCodeStart":1761,"sourceCodeEnd":1797,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1761-L1797","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Remove `--no-disable-hybrid-kv-cache-manager` and let vLLM decide automatically.","Identify the incompatible feature/connector from the auto-disable logic and drop it if HMA matters more.","If a custom KV connector is involved, implement `SupportsHMA` (kv_connector/v1/base.py; for MultiConnector every child must support it)."],"exampleFix":"# before\nvllm serve model --no-disable-hybrid-kv-cache-manager \\\n  --kv-transfer-config '{...connector...}'\n\n# after\nvllm serve model --kv-transfer-config '{...connector...}'","handlingStrategy":"validation","validationCode":"# simplest guard: never force it on\nif kv_connector_used and disable_hybrid_kv_cache_manager is False:\n    disable_hybrid_kv_cache_manager = None  # let vLLM auto-decide","typeGuard":null,"tryCatchPattern":"try:\n    LLM(**args)\nexcept ValueError as e:\n    if \"Hybrid KV cache manager was explicitly enabled\" in str(e):\n        args[\"scheduler_config\"].disable_hybrid_kv_cache_manager = None\n    else:\n        raise","preventionTips":["Do not pass --no-disable-hybrid-kv-cache-manager alongside KV connectors unless SupportsHMA is implemented","Prefer auto (None) for HMA enablement"],"tags":["kv-cache","hybrid-attention","kv-connector","startup-config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}