{"record":{"id":"064504fd41b32880","repo":"vllm-project/vllm","slug":"mooncakestoreconnector-does-not-support-unsuppor","errorCode":null,"errorMessage":"MooncakeStoreConnector does not support: {unsupported}","messagePattern":"MooncakeStoreConnector does not support: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/connector.py","lineNumber":124,"sourceCode":"        for g_idx, g in enumerate(kv_cache_config.kv_cache_groups):\n            spec = g.kv_cache_spec\n            if isinstance(spec, CrossAttentionSpec):\n                unsupported.append(f\"group {g_idx}: CrossAttentionSpec\")\n            # Enforce Mamba align mode\n            if isinstance(spec, MambaSpec) and spec.block_size != cache_block_size:\n                unsupported.append(\n                    f\"group {g_idx}: MambaSpec with block_size=\"\n                    f\"{spec.block_size} != cache_config.block_size=\"\n                    f\"{cache_block_size} (mamba_cache_mode != 'align')\"\n                )\n        pcp = vllm_config.parallel_config.prefill_context_parallel_size\n        dcp = vllm_config.parallel_config.decode_context_parallel_size\n        if len(kv_cache_config.kv_cache_groups) > 1 and pcp * dcp > 1:\n            unsupported.append(\n                f\"PCP/DCP > 1 (pcp={pcp}, dcp={dcp}) with hybrid attention\"\n            )\n        if unsupported:\n            raise ValueError(\n                \"MooncakeStoreConnector does not support: \" + \"; \".join(unsupported)\n            )\n\n    def __init__(\n        self,\n        vllm_config: VllmConfig,\n        role: KVConnectorRole,\n        kv_cache_config: KVCacheConfig | None = None,\n    ):\n        super().__init__(\n            vllm_config=vllm_config,\n            role=role,\n            kv_cache_config=kv_cache_config,  # type: ignore[arg-type]\n        )\n        assert vllm_config.kv_transfer_config is not None\n        assert kv_cache_config is not None, \"kv_cache_config is required\"\n        self.kv_role = vllm_config.kv_transfer_config.kv_role\n        # Capacity-only: contributes its segment to the store pool but transfers","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/connector.py#L106-L142","documentation":"MooncakeStoreConnector validates the vLLM config before use and raises a single aggregated ValueError listing every unsupported combination. Currently it rejects: (a) hybrid-attention models whose MambaSpec block_size differs from cache_config.block_size unless mamba_cache_mode == 'align', and (b) multiple KV cache groups combined with prefill_context_parallel_size * decode_context_parallel_size > 1 (hybrid attention under CP).","triggerScenarios":"Loading a hybrid SSM/attention model (e.g. a Mamba-2 hybrid) with --kv-transfer-config pointing at MooncakeStoreConnector while cache block sizes of the mamba allocator and the attention allocator disagree, or enabling PCP/DCP > 1 on a model whose KV cache splits into more than one group.","commonSituations":"Serving Qwen3-Next / Falcon-H1 / Zamba-class hybrids with P2P KV offload; setting -y or CP flags together with hybrid models; block_size defaults changing between vLLM versions so the two allocators no longer line up.","solutions":["Set kv_connector_extra_config['mamba_cache_mode']='align' so the mamba cache uses the same block size as the attention cache","Ensure cache_config.block_size matches the MambaSpec block size (e.g. run with the default block size the model expects) so the first unsupported condition disappears","Disable context parallelism (pcp/dcp = 1) for hybrid-attention models when using this connector","Switch to a connector that supports your topology (e.g. LMCache/NIXL) if CP with hybrid models is a hard requirement"],"exampleFix":"# before\nkv_transfer_config = KVTransferConfig(\n    kv_connector=\"MooncakeStoreConnector\",\n    kv_role=\"kv_both\",\n)\n\n# after (align mamba blocks with the attention cache)\nkv_transfer_config = KVTransferConfig(\n    kv_connector=\"MooncakeStoreConnector\",\n    kv_role=\"kv_both\",\n    kv_connector_extra_config={\"mamba_cache_mode\": \"align\"},\n)","handlingStrategy":"validation","validationCode":"pc = vllm_config.parallel_config\ngroups = kv_cache_config.kv_cache_groups if kv_cache_config else []\nasserted = (pc.prefill_context_parallel_size * pc.decode_context_parallel_size) <= 1 or len(groups) <= 1\nmamba_ok = all(\n    spec.block_size == cache_config.block_size\n    or extra_config.get(\"mamba_cache_mode\") == \"align\"\n    for g in groups for spec in getattr(g, \"mamba_specs\", []) or []\n)\nif not (asserted and mamba_ok):\n    raise ValueError(\"config unsupported by MooncakeStoreConnector\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set mamba_cache_mode='align' for hybrid models with this connector","Smoke-test the connector with your exact parallel layout before production","Watch release notes: supported hybrid/CP combinations expand over versions"],"tags":["mooncake","kv-transfer","hybrid-attention","mamba","context-parallel","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}