vllm-project/vllm · error · ValueError

MooncakeStoreConnector does not support: {unsupported}

Error message

MooncakeStoreConnector does not support: {unsupported}

What it means

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).

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/connector.py:124

        for g_idx, g in enumerate(kv_cache_config.kv_cache_groups):
            spec = g.kv_cache_spec
            if isinstance(spec, CrossAttentionSpec):
                unsupported.append(f"group {g_idx}: CrossAttentionSpec")
            # Enforce Mamba align mode
            if isinstance(spec, MambaSpec) and spec.block_size != cache_block_size:
                unsupported.append(
                    f"group {g_idx}: MambaSpec with block_size="
                    f"{spec.block_size} != cache_config.block_size="
                    f"{cache_block_size} (mamba_cache_mode != 'align')"
                )
        pcp = vllm_config.parallel_config.prefill_context_parallel_size
        dcp = vllm_config.parallel_config.decode_context_parallel_size
        if len(kv_cache_config.kv_cache_groups) > 1 and pcp * dcp > 1:
            unsupported.append(
                f"PCP/DCP > 1 (pcp={pcp}, dcp={dcp}) with hybrid attention"
            )
        if unsupported:
            raise ValueError(
                "MooncakeStoreConnector does not support: " + "; ".join(unsupported)
            )

    def __init__(
        self,
        vllm_config: VllmConfig,
        role: KVConnectorRole,
        kv_cache_config: KVCacheConfig | None = None,
    ):
        super().__init__(
            vllm_config=vllm_config,
            role=role,
            kv_cache_config=kv_cache_config,  # type: ignore[arg-type]
        )
        assert vllm_config.kv_transfer_config is not None
        assert kv_cache_config is not None, "kv_cache_config is required"
        self.kv_role = vllm_config.kv_transfer_config.kv_role
        # Capacity-only: contributes its segment to the store pool but transfers

View on GitHub (pinned to c794754062)

Solutions

1. Set kv_connector_extra_config['mamba_cache_mode']='align' so the mamba cache uses the same block size as the attention cache
2. 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
3. Disable context parallelism (pcp/dcp = 1) for hybrid-attention models when using this connector
4. Switch to a connector that supports your topology (e.g. LMCache/NIXL) if CP with hybrid models is a hard requirement

Example fix

# before
kv_transfer_config = KVTransferConfig(
    kv_connector="MooncakeStoreConnector",
    kv_role="kv_both",
)

# after (align mamba blocks with the attention cache)
kv_transfer_config = KVTransferConfig(
    kv_connector="MooncakeStoreConnector",
    kv_role="kv_both",
    kv_connector_extra_config={"mamba_cache_mode": "align"},
)

pc = vllm_config.parallel_config
groups = kv_cache_config.kv_cache_groups if kv_cache_config else []
asserted = (pc.prefill_context_parallel_size * pc.decode_context_parallel_size) <= 1 or len(groups) <= 1
mamba_ok = all(
    spec.block_size == cache_config.block_size
    or extra_config.get("mamba_cache_mode") == "align"
    for g in groups for spec in getattr(g, "mamba_specs", []) or []
)
if not (asserted and mamba_ok):
    raise ValueError("config unsupported by MooncakeStoreConnector")

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• --use-replayssm is incompatible with KV connectors (P/D disa
• Mooncake Transfer Engine initialization failed.
• block_size ({self.block_size}) must be a multiple of hash_bl
• Partial-tail offloads for one request must share a boundary
• --use-replayssm supports prefix caching only in align mode;

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